<h1 id="distributed-interactive-simulation">Distributed Interactive Simulation</h1>
<h2 id="i.-introduction">I. Introduction</h2>
<h3 id="a.-dis-background">a. DIS Background</h3>
<p>Distributed Interactive Simulation (DIS) is a software standard used to help implement military simulation applications. The simulations that use DIS have hosts connected by a network, and the DIS protocol helps exchange information about the combat units in the simulation. This includes what types of vehicles are used, how they interact, or how they are used in combat operations. DIS is used in many United States Department of Defense (DoD) applications, and has been for decades.</p>
<p>The software standard DIS involves definitions for dozens of network messages that are exchanged between hosts. The syntax and semantics of the messages, which are called Protocol Data Units (PDUs) in DIS, are carefully defined. The PDUs can be exchanged between CPUs of multiple designs, running many types of operating systems, and these operations can be done in multiple software languages. This helps make DIS flexible and effective.</p>
<p>To achieve its simulation operation objectives the DIS standard includes more than just message format issues. The syntax of messages is defined, but DIS also includes more information. Individual messages also include positions expressed in a particular global coordinate system, for example, and there are many other DIS rules that solve problems, such as detecting the presence of netowrked entities, or performing combat operations. The logical operations necessary to complete these operations becomes tricky and non-obvious. DIS simulation users must learn how to make use of the DIS operations, and this can become difficult unless the implementor knows how to do it. There is a standard for DIS defined by the Institute of Electrical and Electronics Engineers (IEEE) standards organization known as IEEE-1278.1. However in any standard the emphasis is placed on achieving unambigous and accurate definitions rather than helpful descriptions of how to make use of the defined features.</p>
<p>That is part of what this document is intended to achieve: describe and teach the effective implementation of the features that DIS can implement. The DIS standard is useful, widely used, and at the same time those using it can find it difficult to implement real application features due to the complex nature involved. It’s helpful to have clear explanations.</p>
<p>That’s only part of it. DIS is flexible, and can be used in a range of applications. Simply listening to and saving the messages sent on the network from a live exercise can be very useful to analysts. They can later used the saved messages to examine what real vehciles or people actually did and use the collected data to help evaluate the effectiveness of combat tactics. Learning how this works, which can involve essentially no graphical display of the entities in a simuation at all, is a change from what’s called the Networked Virtual Environment&quot; (NVE) since there is no “virtual” graphics aspect for the user to view.</p>
<p>The problem space of DIS is common in many ways to those that appear in the commercial game entertainment world. It is very unusual for commercial entertainment games to use DIS, but the technological implementation problems faced by games are often similar to those faced by DIS. If you’re a commercial game programmer, some of the issues discussed here may help your commercial implementations.</p>
<p>There are other features of DIS that will be assessed as well. From an practical or even academic standpoint the number of questions raised through DIS can be enormous. It’s therefore helpful to have specialists cooperate on this DIS Tutorial project. The tutorial project’s structure is, one hopes, helpful in allowing experts on a topic to supply their answers while not causing issues with other sections of the tutorial.</p>
<h3 id="b.-dis-tutorial-purpose">b. DIS Tutorial Purpose</h3>
<p>Often the people who need to learn something about DIS are programmers who are thrown head-first into the problem. They’re given some vague instructions, usually summed up as “Hey, we need to implement DIS in our application. Go make it work.” Sometimes the programmers don’t have prior experience with distributed simulations or virutal worlds. They often work on the project for a few weeks before moving on to something else, so they need to learn about the subject quickly. They’re OK with coding, and often with network programming, but using DIS often involves a problem domain that is not clear to newcomers. For example, one would think that it is easy to direct an object in a virtual world to move one meter northwest. This is tricker than it may seem at first glance. What coordinate system is being used, and is that using metric or imperial units? How does one uniquely select an object so that it and it alone moves? Learning about each of these tasks can take a programmer days to unravel if he must rely on only the IEEE standard.</p>
<p>Another audience for this document is military or support personnel responsible for making existing DIS simulations work. They usually have good understanding of the military problem domain and perhaps the basics of networking and software installation. While they are subject matter experts on the military actions in the simulation, they may not be familiar with the nuts and bolts of how the simulation protocol works. An understanding of how things are done in DIS is often a great help in getting a simulation working, or understanding the limitations and features that are difficult or impossible to implement in a simulation.</p>
<p>Those using simulations that instead of DIS use HLA, TENA or WebLVC can also benefit from this manual. The HLA Realtime Platform Reference Federation Object Model (RPR-FOM) uses many of the concepts from DIS, and so can TENA. So understanding DIS also helps HLA RPR-FOM and TENA users. Sometimes HLA RPR-FOM simulations and DIS simulations communicate with each other via a protocol gateway, and the use of the gateway can be helped by users who appreciate the shared concepts.</p>
<p>Studying the standard in isolation can be confusing if the reader has no familiarity with the problems inherent to distributed simulations. The IEEE-1278 standards document does not usually explain the “why” it choose to solve the problems it did, or even that the problems it solves are in fact problems. This document includes an overview of distributed simulations and the inherent issues faced when implementing them. In order to explain the issues, background information on distributed simulations and virtual worlds is presented. If you already know all this, you can safely skip it. But for most programmers and administrators it provides the context for features or data in DIS that may seem mysterious at first.</p>
<p>DIS consists of a few dozen network messages exchanged between simulations. Understanding the syntax of these messages and how to create and receive them is the easy part of DIS. A deeper understanding of what the semantic content of the messages are, and what problems they are trying to solve, is more difficult and more valuable.</p>
<p>If you just want to sling some code and skip all the throat-clearing and theory, you can start reading the “Protocol Data Units: Exchanging State Information” section.</p>
<p>DIS standardizes the format of network messages but has no formal programming API. If a programmer wants to create what is known as an “Entity State Protocol”, a network message that defines the location and orientation of an object in a simulation, the implementation of DIS is free to choose function calls of either</p>
<pre><code>espdu.setLocation(newLocation);</code></pre>
<p>or</p>
<pre><code>espdu.setLoc(newLocation);</code></pre>
<p>Those who implement the DIS standard can use any API they choose. The code in this document primarily uses the open-dis implementation, which is available at https://github.com/open-dis. There are implementations for several languages, including Java, Javascript, C++, C#, Objective-C, and Python. There are other implementations of DIS, both open source and commercial. There are also many home-grown implementations of the standard that were created by simulation implementors. They just wrote their own DIS implementation, or the portions of the DIS standard they needed. This means that the code-writers out there are likely see differences in the source code of two applications that do the same thing. But if they understand DIS, the objective of this document, they should be able to overcome the implementation issues.</p>
<p>There are other features of DIS that will be assessed as well. From an practical or even academic standpoint the number of questions raised through DIS can be enormous. It’s therefore helpful to have specialists cooperate on this DIS Tutorial project. The tutorial project’s structure is, one hopes, helpful in allowing experts on a topic to supply their answers while not causing issues with other sections of the tutorial.</p>
<h3 id="c.-graphics">c. Graphics</h3>
<p>To take the last topic first, the graphics portion of the shared virtual world is a subject unto itself because of the inherent complex nature of the topic. The art that portrays the shared environment may vary depending on the training objectives. In the commercial world, imagine the graphics of “Call of Duty” or other first person shooter entertainment games. Users who buy the games like good-looking and fast game graphics. In the DoD world, sometimes the training objectives also require high quality and quick graphics operations. For example, some flight simulators that replicate ground attack operations. Some applications also rooted in the DoD can instead use 2D maps to portray a shared environment. The objective of the simulation in this case is to provide users with information about where vehicles and units are, rather than individual vehicle appearance. A map-based graphics simulator may also require position updates once every few seconds rather than several times per second.</p>
<p>The choices about what graphics to include in a DIS application depend entirely on the DoD’s training objectives. An implementor may be able to use Google Maps or Open Street Maps, for example. The map graphics are not realistic 3D displays of vehicles, but may achieve the simulation objectives. Alternatively some applications can use 3D graphics in a manner reminiscent of modern commercial games. There are many ways to draw the 3D images we see on the screen, from OpenGL and Direct3D to higher level scene graphs, such as OpenInventor or X3D. At an even higher level of abstraction objects can be rendered with the aid of a 3D game engine such as Lumberyard or Unity. A DIS application may have rudimentary 3D graphics instead of photorealistic 3D graphics, depending on the training use. Again, the audience being trained may benefit from high quality graphics, or still be well trained by a graphics system that is simple but effective in accomplishing the training objective.</p>
<p>Computer graphics is a large and complex subject, and instruction or examples often depend on the graphics standard chosen to describe the environment. We will discuss some graphics implementations for both for 2D maps and 3D applications. In some understandings, graphics use in simulations can be distinguished as being separate from DIS networking. The reality is that graphics are often used in simulations that use DIS, and from a practical standpoint a DIS tutorial has to at least mention how to use it.</p>
<h3 id="d.-formats-and-semantics">d. Formats and Semantics</h3>
<p>Before the distributed simulation application can be implemented there needed to be a way to exchange <em>state information</em> between simulators. State information includes data about a participant in the simulation that is transmitted to other simulation hosts. In the case of a tank, the state information includes its position, the direction the vehicle is facing, how fast it is moving, whether it is on fire, and subjects such as which way the turret is pointing. It’s this state information and the format that it is exchanged in that DIS standardizes. Once the state information is exchanged the graphics components we just described above can be used to draw the scene that the users see.</p>
<p>It is in the government’s interest to have simulators interoperate with each other, in particular to prevent vendor lock-in. If the protocol for exchanging state information is owned by a company and that company can prevent simulator competitors from entering the market, or charge more to make their simulators interoperate with those from other companies. To be useful the DIS protocol had to be a <em>standard</em>, and an open one. Simply providing a language implementation that did the job without also specifying what was being exchanged was inadequate. So SISO refined the SIMNET network protocol and developed a formal description of it, then took it to the IEEE, where it was approved as an international standard (IEEE-1278.1). From that point on anyone could buy the IEEE standard document and then write their own implementation of the protocol.</p>
<p>As is inevitable with these things, the standard has to be maintained and updated in light of experience and new technology. From the late 80’s until about 1995 the DARPA SIMNET protocol was used; this predated the adoption of DIS as an IEEE standard. The first major release of a standard DIS was DIS version 5, in 1995. It was updated with version 6, in 1998, when a few new network messages were added. Version 7 was adopted in 2012, and that version maintained an almost complete backwards compatiblity to the DIS version 5 of 1995. At the same time it added a few new PDUs (network messages) related to directed energy weapons and also clarified the semantics of protocol. SISO continues to support and update DIS in working groups, today in parallel with the HLA RPR-FOM.</p>
<h3 id="e.-networking">e. Networking</h3>
<p>Sending the messages defined by DIS involves using, almost always, the TCP/IP networking system. That’s simply because TCP/IP has become so widespread. Once upon a time there were other software networking standards, such as DECnet, IBM Systems Network Architecture (SNA), Open Systems Interconnection (OSI), or AppleTalk. Those high level network protocols are simply not in use to much of an extent these days. In the case of DIS, can be exceptions to the use of TCP/IP in radio alert applications, but this is somewhat rare.</p>
<p>Using TCP/IP to send DIS messages is useful. It is simple enough to use TCP, UDP, broadcast, and multicast. For the most part in this document the objective is to be as simple as possible when discussing the subject. Network programming is intended to stay at the highest levels possible, excluding, to the extent possible, such topics as the IP or lower levels.</p>
<h3 id="f.-parting-thoughts">f. Parting Thoughts</h3>
<p>Given the technology of the era, the architects of DIS were visionary. Even decades after it was developed and standardized it still holds up quite well. The research it prompted was trailblazing, and served as the starting point for many military simulations and then entertainment industry game applications. The ideas worked out in DIS are still widely used today.</p>
<h3 id="g.-further-reading">g. Further Reading</h3>
<p><strong>Simulation Interoperabilty Standards Organization (SISO):</strong> http://sisostds.org/<br> <strong>The IEEE DIS Standard, 1998 (Version 6):</strong> https://standards.ieee.org/findstds/standard/1278.1a-1998.html<br> <strong>DIS Wikipedia:</strong> https://en.wikipedia.org/wiki/Distributed_Interactive_Simulation<br> <strong>DIS Plain and Simple, another document that provides information about DIS:</strong> https://www.sisostds.org/DigitalLibrary.aspx?Command=Core_Download&amp;EntryId=29302<br> <strong>SIMNET wikipedia:</strong> https://en.wikipedia.org/wiki/SIMNET<br> <strong>SIMNET History:</strong> http://www.iitsec.org/about/awardsandrecognition/Documents/2015_FellowPaper_Miller.pdf<br> <strong>Still More SIMNET History:</strong> http://www.dtic.mil/dtic/tr/fulltext/u2/a294786.pdf<br> <strong>A whole website devoted to SIMNET history:</strong> http://simnet-history.org/<br> <strong>Networked Graphics: Building Networked Games and Virtual Environments</strong>, Anthony Steed and Manuel Oliveira. https://www.amazon.com/Networked-Graphics-Building-Virtual-Environments/dp/0123744237</p>
<p><strong>Networked Virtual Environments: Design and Implementation</strong>, Sandeep Singhal and Mike Zyda. Sadly out of print. https://www.amazon.com/Networked-Virtual-Environments-Design-Implementation/dp/0201325578/</p>
<h2 id="dis-history">2. DIS History</h2>
<p>DIS arose from a Defense Advanced Research Agency (DARPA) project in the 1980’s called SIMNET. At the time TCP/IP and high speed networks were just getting their legs, computers and networks were becoming powerful enough to do the computational operations needed, and 3D graphics was in its infancy.</p>
<p>A screen capture from an early SIMNET application is shown below:</p>
<p><img src="I_Introduction/images/SimnetDisplay.jpg"/></p>
<p>Each participant is in a SIMNET application controlled a tank, and each simulator views the shared virutal battlefield. All the vehicles interacted in the same shared enviroment. If one simulator causes the tank it controls to move, the other partipants see that movement, in real time.</p>
<p>The simulators of the era sometimes had displays that replicated a soldier’s view of the battlefield, but the host running the simulation wasn’t networked with other hosts. Each simulator worked in isolation, and an aircraft simulator couldn’t see a tank controlled by another simulator. The idea of SIMNET–quite advanced for the time–was to create a virtual, shared battlefield in which all participants on multiple computers could see and interact with each other. SIMNET’s major accomplishment–it was arguably one of the first large real-time distirubted virtual world–was to serve as a basis for the research that allowed DIS to happen.</p>
<p>DARPA projects were intended to transition out of the incubator research phase and into useful actual implementations. The SIMNET project worked out many of the state information exchange issues that were needed. Once that was done it needed to be standardized and refined outside of DARPA. The group that would eventually do this was Simulation Interoperability Standards Group (SISO) that took over development of the network protocol portion of the project, which they renamed to DIS. SISO developed DIS in a series of workshops held from 1989 to 1996. Once the protocol was developed they took the relevant documents to the IEEE standards group and achieved DIS standard approval.</p>
<p>In today’s commercial game world games like “Call of Duty” or “World of Tanks” do shared environments between hosts routinely. The companies that own these games make a lot of money selling such applications to the public. At the time of SIMNET the concept of a shared, networked environment was revolutionary.</p>
<h1 id="example-dis-applications">Example DIS Applications</h1>
<p>There are a number of example applications of DIS available. This section simply shows a few so the reader can get an idea of what DIS is capable of helping implement. Some of the applicatons shown are commercial.</p>
<h2 id="metavr-and-vrsg">MetaVR and VRSG</h2>
<p>The company MetaVR has created an application that uses DIS called the Virtual Reality Scene Generator (VRSG). The VRSG application can implement views of terrain, with varying weather, and that includes aircraft.</p>
<p><a href="http://www.metavr.com/products/vrsg/vrsgstandalone.html" title="Title">MetaVR</a> Has a web page devoted to the Virtual Reality Scene Generator application. Another web site for VRSG is at <a href="http://www.metavr.com/products/vrsg/vrsgoverview.html%22Title%22">here</a>, which features vehicles at the Yuma proving grounds and the Strait of Hormuz.</p>
<p>http://www.metavr.com/products/vrsg/vrsgstandalone.html</p>
<p><img src="I_Introduction/images/disApplications/vrsgHelo.jpg" alt="Alt text" /> <img src="I_Introduction/images/disApplications/IranianAircraftModels.jpg" alt="Alt text" /> <img src="I_Introduction/images/disApplications/Hormuz.jpg" alt="Alt text" /></p>
<h2 id="battlespace-simulations-and-modern-air-combat-environment">Battlespace Simulations and Modern Air Combat Environment</h2>
<p>This application is put out by Battlespace Simulations, Inc. Their web site is at <a href="https://www.bssim.com/mace/" title="Title">MASE</a> According to company Battlespace Simulations,</p>
<blockquote>
<p>MACE is a physics-based, many-on-many simulation and threat environment with a large order of battle, ideally suited for both standalone mission rehearsal and distributed mission simulation. MACE provides computer generated forces (CGF), sometimes called semi-autonomous forces (SAF), as well as scenario creation, management and IOS features. Using MACE, you can quickly and easily extend your distributed simulation framework. MACE supports the Distributed Interactive Simulation (DIS) architecture including simulation management, entity state, fire, detonate and emissions PDUs.</p>
</blockquote>
<div class="figure">
<img src="I_Introduction/images/disApplications/Mace.jpg" alt="Alt text" />
<p class="caption">Alt text</p>
</div>
<h2 id="acm">ACM</h2>
<p>The ACM project is a free game that can be used in the debian operating system.</p>
<p>A major web site is at <a href="https://packages.debian.org/sid/games/acm" title="Title">ACM</a></p>
<p>According to the site, this is</p>
<blockquote>
<p>multiplayer aerial combat simulation. Players engage in air to air combat against one another using heat seeking missiles and cannons.</p>
</blockquote>
<blockquote>
<p>Main features include:</p>
</blockquote>
<blockquote>
<ul>
<li>Simulation with 6 degrees of freedom.</li>
<li>Structural limit to the vertical positive/negative load.</li>
<li>Classic instruments, navigation and head-up display (HUD).</li>
<li>Several aircraft models implemented, both civil and military.</li>
<li>Two scenes provided, with many runways and radio stations.</li>
</ul>
</blockquote>
<div class="figure">
<img src="I_Introduction/images/disApplications/debian.png" alt="Alt text" />
<p class="caption">Alt text</p>
</div>
<h2 id="diswebgateway">DISWebGateway</h2>
<p><a href="https://github.com/open-dis/DISWebGateway" title="Title">DISWebGateway</a></p>
<p>DISWebGateway is a small open-dis project. The application reads native DIS traffic on the network, then forwards it to a web server. The DIS traffic can be interpreted by a Javascript implementation of DIS and used in a variety of ways. Users can visit a site on the server and see the effect.</p>
<p>This can be quite interesting. The server allows access to a huge range of capabilities, including remote web-based data The screen capture below shows an entity mapped by the Google Maps utility. OpenStreetMap is also supported.</p>
<div class="figure">
<img src="I_Introduction/images/disApplications/WebBasedApp.tiff" alt="Alt text" />
<p class="caption">Alt text</p>
</div>
<h2 id="dod-simulation-standards">3. DoD Simulation Standards</h2>
<p>DIS is not the only standard used by contributors to the Department of Defense or other the defense departments of other nations. The other standards include High Level Architecture (HLA), Test and Training Enabling Architecture (TENA), and WebLVC. They all perform many of the same operations as DIS, and in fact copy some of the ideas of DIS.</p>
<p>Each of these protocols is discussed in their own section.</p>
<h3 id="b.-high-level-architecture">b. High Level Architecture</h3>
<p>DIS was the first standard for distributed simulations. Some time later it was believed that it could be improved upon by using different approaches than those of the 80’s, when DIS was created. This resulted in High Level Architecture (HLA).</p>
<p>There are some important differences between DIS and HLA, but they often share important features as well, particularly when describing combat operations. The HLA architecture can cover a wider range of problems in addition to those addressed by DIS.</p>
<h4 id="i.-off-site-tutorials">i. Off-Site Tutorials</h4>
<p>There are several interesting tutorials about HLA already present. Rather than attempting to supply yet another, the approach in this section is to simply link to the existing HLA tutorials.</p>
<p>Here’s a list of some online HLA tutorials:</p>
<h5 id="pitch-technologies">Pitch Technologies</h5>
<p><a href="http://www.pitchtechnologies.com/hlatutorial/">Pitch Technologies HLA Tutorial</a></p>
<h5 id="mcgill-university">McGill University</h5>
<p><a href="http://msdl.cs.mcgill.ca/people/hv/teaching/MSBDesign/COMP762B2003/presentations/HLA1.pdf">McGill University, Roger MacFarlane</a></p>
<h5 id="center-for-object-technology">Center for Object Technology</h5>
<p><a href="http://www.cit.dk/COT/reports/reports/Case6/06/cot-6-06.pdf">How to become an HLA guru in a short(er) time</a></p>
<h5 id="georgia-institute-of-technology-computational-science-and-engineering-division-richard-m.-fujimoto">Georgia Institute of Technology, Computational Science and Engineering Division, Richard M. Fujimoto</h5>
<p><a href="http://www.acm-sigsim-mskr.org/Courseware/Fujimoto/Slides/FujimotoSlides-20-HighLevelArchitectureIntro.pdf">The High Level Architecture: Introduction</a></p>
<h4 id="ii.-hla-and-dis">ii. HLA and DIS</h4>
<h5 id="rpr-fom">RPR-FOM</h5>
<p>HLA was designed and built to be more general than DIS, but at the same time it was very useful to have HLA configurations that did many of the same things. Readers of the tutorials above know something about Federation Object Modules (FOMs). The FOMs define the objects and attributes in an HLA federation.</p>
<p>SISO realized that it would be useful to define a FOM similar to that of DIS, and that’s exactly what they did. The Real-time Platform Reference Federation Object Model <a href="https://www.sisostds.org/DesktopModules/Bring2mind/DMX/Download.aspx?Command=Core_Download&amp;EntryId=30823&amp;PortalId=0&amp;TabId=105">(RPR-FOM)</a> defines a FOM that copies many DIS concepts. RPR-FOM makes it easier to work with DIS appliations.</p>
<p>Consider the location of a simulation entity. In an application RPR-FOM object we can define an object attribute:</p>
<pre><code>&lt;field&gt;
    &lt;name&gt;WorldLocation&lt;/name&gt;
    &lt;dataType&gt;WorldLocationStruct&lt;/dataType&gt;
    &lt;semantics&gt;-NULL-&lt;/semantics&gt;
 &lt;/field&gt;</code></pre>
<p>The simulated object includes an attribute defining its location in the world. The format of this attribute is identical to that used by DIS. As we will see, the WorldLocationStruct defined in the RPR-FOM is exactly the same as that used in DIS.</p>
<pre><code>&lt;fixedRecordData&gt;
                &lt;name&gt;WorldLocationStruct&lt;/name&gt;
                &lt;encoding&gt;HLAfixedRecord&lt;/encoding&gt;
                &lt;semantics&gt;Location of the origin of the entity&#39;s coordinate system shall be specified by a set of three coordinates: X, Y, and Z. The shape of the earth shall be specified using DMA TR 8350.2, 1987. The origin of the world coordinate system shall be the centroid of the earth, with the X-axis passing through the prime meridian at the equator, the Y-axis passing through 90 degrees east longitude at the equator, and the Z-axis passing through the north pole. These coordinates shall represent meters from the centroid of the earth.&lt;/semantics&gt;
                &lt;field&gt;
                    &lt;name&gt;X&lt;/name&gt;
                    &lt;dataType&gt;WorldLocationOffset&lt;/dataType&gt;
                    &lt;semantics&gt;-NULL-&lt;/semantics&gt;
                &lt;/field&gt;
                &lt;field&gt;
                    &lt;name&gt;Y&lt;/name&gt;
                    &lt;dataType&gt;WorldLocationOffset&lt;/dataType&gt;
                    &lt;semantics&gt;-NULL-&lt;/semantics&gt;
                &lt;/field&gt;
                &lt;field&gt;
                    &lt;name&gt;Z&lt;/name&gt;
                    &lt;dataType&gt;WorldLocationOffset&lt;/dataType&gt;
                    &lt;semantics&gt;-NULL-&lt;/semantics&gt;
                &lt;/field&gt;</code></pre>
<p>The closeness of RPR-FOM to DIS is quite useful for many applicatons.</p>
<h4 id="iii.-hla-and-simulation-size">iii. HLA and Simulation Size</h4>
<p>HLA can almost always create simulations that can include more entities than DIS-based applications.</p>
<p>Distributed simulations transmit simulation entity attribute values between hosts. This may include information such as position and orientation, and also describe the entity’s speed and acceleration. As we shall see later in descriptions of DIS’s entity state PDU, DIS will transmit all of these attribute values every few seconds even if they do not change. This increases the network use for every entity in the simulation. A simulated truck parked next to a road will send updates every few seconds for all of the attributes mentioned above, even though they did not change. The increased use of the network, which has a limited capacity, can reduce the number of entities the simulation can support.</p>
<p>In contrast HLA can send updates oof the same attributes to other hosts only when they are changed. A parked truck does not change its position or orientation, and its speed and acceleration remain at zero while parked. HLA can send no updates at all to the other participants in the simulation. This drives down network use by letting HLA applications use less bandwidth. In the end, HLA can suppport more simulated entities because it reduces network use for each simulated entites.</p>
<h5 id="iv.-network-message-formats">iv. Network Message Formats</h5>
<p>HLA took some fundamentally different technical approaches when compared to those of DIS. DIS made the choice to standardize the syntax and semantics of a few dozen messages sent on the network. All programming languages that can read and send binary data messages are capable of decoding and sending DIS messages. This includes C, C++, Java, Javascript, Objective-C, Python, and dozens of others. Sometimes simulation application programmers like to use specific languages for various reasons. Python and Javascript have been interesting and powerful programming languages of late.</p>
<p>HLA took a different approach. Rather than define the format of messages, it uses standardized Application Protocol Interface (API) for a limited set of languages. The list of APIs for HLA is at <a href="https://www.sisostds.org/APIs.aspx">SISO</a>. Every API is, by definition, specific to a programming language.</p>
<p>The API defines a set of function calls, and the function calls must be language-specific. The primary APIs for HLA are C++ and Java. (There’s also a rarely used API called “Web Services.” Web services refers to a technology that seems not very usable in distributed simulations due to its high latency rates, though it is still supported by SISO. There are today better performing web technologies which will be discussed.)</p>
<p>The full APIs defined are available at SISO. For example, a function in the API for a Java version of the <a href="https://www.sisostds.org/DesktopModules/Bring2mind/DMX/Download.aspx?Command=Core_Download&amp;EntryId=42469&amp;PortalId=0&amp;TabId=105">HLA API</a> looks like this:</p>
<pre><code>virtual void discoverObjectInstance (
 ObjectHandle theObject, // supplied C1
 ObjectClassHandle theObjectClass, // supplied C1
 const char * theObjectName) // supplied C4
throw (
 CouldNotDiscover,
 ObjectClassNotKnown,
 FederateInternalError) = 0;</code></pre>
<p>There is also a C++ API function that performs the same operation, but the syntax of that function call in C++ API element is of course compliant with the C++ language.</p>
<p>Developers who want to use other languages, such as Python or Javascript, may run into problems if in the end a call must be made to the Java or C++ APIs for those languages to access HLA. In contrast the developer can directly decode the DIS messages in the language he prefers to use.</p>
<p>Another interesting problem is how the HLA API function calls are actually achieved. The API defines the names of function calls and what they do, but do not define how the function works. In the end, messages must be exchanged between hosts, and HLA does not define the message format used to accomplish this. The message format to achieve the result of discoverObjectInstance is determined by the vendor that implements the HLA API.</p>
<p>At the abstract level the function above is a call to search for an object instance. But at the practical level the API is silent about how to accomplish discoverObjectInstance(). The messages exchanged between hosts may contain data in the <a href="https://en.wikipedia.org/wiki/Endianness">big or little endian format</a>, and there may be several messages passed between simulation hosts. Since HLA defines the API, but not the nature of messages necessary to implement the API, in practice every implementation of HLA has different binary messages issued on the network.</p>
<p>The lack of a network standard can make multiple applications working together difficult. Imagine two HLA applications that use exactly the same HLA Federation Object Model (FOM). The simulation’s FOM is a configuration component that defines the simulation’s entities and the entity attributes they have. TankApp uses a vendor of HLA that sells a product called SuperHLA, while the application we want it to workk with, called AircraftApp, uses an HLA implementation product named AwesomeHLA. The two vendors use exactly the same API, but the format of messages they put on the network are different from each other, unknown, and incompatible. SuperHLA cannot receive messages sent by AwesomeHLA, and AwesomeHLA cannot receive messages sent by SuperHLA. Perhaps the programmers for SuperHLA decided to use little endian messages, while AwesomeHLA developers chose to use big endian formats. The HLA implementations have no idea about how they should decode the binary messages of the other HLA implementation.</p>
<p>If the two appliations are to interoperate one option is to use the same HLA implementation, either SuperHLA or AwesomeHLA, in both applications. HLA adopted a strong interoperability standard, and it should be possible to point the application at a different HLA library and run it without error or recompiling. In the case of the TankApp and AircraftApp simulations we should be able to pick one of the HLA implementation libraries, use it in both applications, and start the applications again without recompilation. (In practice there seems to be some reluctance by program managers to do this without a good deal of testing.)</p>
<p>Another option is for each application to share its data in DIS format. In addition to using HLA internally the application may issue a feed to the network about entity movement in DIS format. Perhaps the other application that can then receive the DIS feed and share it into its own HLA implementation. The TankApp uses SuperHLA and also issues DIS traffic; AircraftApp uses software to read the DIS issued by TankApp and feed the information into AwesomeHLA.</p>
<p>The DIS solution becomes more practical as the two applicatons start becoming more differing. For example imagine TankApp has a slightly different FOM than AircraftApp. After that four other applications are added to the interaction pool with the intention of all six applications working with each other. The applications use slightly different FOMs, and three differnet versions of HLA by default. For a situation such as that described above, DIS can be a useful tool. Examples of this include that of Interservice/Industry Training, Simulation and Education Conference <a href="http://exhibits.iitsec.org/2016//custom/Playbook_OBW_NTSAfinal1110.pdf">I/ITSEC</a>, called Operation Blended Warrior.</p>
<h4 id="v.-conclusions">v. Conclusions</h4>
<p>HLA provides a number of advances over DIS, but also has some language-based restrictions.</p>
<p>There are several guides to HLA that are better than what I could write. You should read them.</p>
<h3 id="c.-test-and-training-enabling-architecture-tena">c. Test and Training Enabling Architecture (TENA)</h3>
<p>Test and Training Enabling Architecture (TENA) is another simulation standard. It’s a very interesting and powerful technology.</p>
<p>TENA was developed by the US Department of Defense, and was intended to include test and training systems on the range.</p>
<h4 id="i.-tena-web-site">i. TENA Web Site</h4>
<p>The <a href="https://www.tena-sda.org/">TENA Website</a> is maintained by the United States Office of the Secretary of Defense Test Resource Management Center (TRMC), which runs the TENA program.</p>
<h4 id="ii.-tena-license">ii. TENA License</h4>
<p>According to wikipedia,</p>
<p>“The TENA software was developed for use by the United States Government with unlimited rights. The software is provided freely for the purpose of promoting interoperability among United States Department of Defense systems. There are no <a href="https://en.wikipedia.org/wiki/International_Traffic_in_Arms_Regulations">International Traffic in Arms Regulations (ITAR)</a> or export restrictions in using the TENA middleware and related TENA products at an international site, although any restrictions for user provided object models, software, or documents are the responsibility of the author(s) of those products. Use of the TENA software (source code and binary code) by individuals is permitted only upon acceptance of terms and conditions available at the <a href="https://www.tena-sda.org/">TENA web site</a> after login.”</p>
<h4 id="iii.-access">iii. Access</h4>
<p>TENA requires an account to download the runtime components, but the TENA organization is open to DoD and DoD vendors. Users who register with TENA can download the runtime software for no charge. Some free implementation software is also available for download. It’s strongly suggested that you register at the TENA-sda site.</p>
<h4 id="iv.-tena-tutorial">iv. TENA Tutorial</h4>
<p>One of the things that makes TENA fascinating and powerful is its simularity to Common Object Request Broker Architecture (CORBA). CORBA is, among other things, a form of remote objects. Use of remote objects often greatly increases programmer productivity.</p>
<p>An introduction to <a href="https://www.tena-sda.org/display/TENAintro/Documentation">TENA</a> is available.</p>
<p>An image of the TENA implementation:</p>
<p><a href="images/TENA.tiff">TENA</a></p>
<h4 id="v.-tena-networking">v. TENA Networking</h4>
<p>In addition to the TENA software the DoD supports network implementations at many training and evaluaton sites. This is called Joint Mission Environment Test Capability JMETC. Documents explaining JMETC are available at the TENA web site.</p>
<h3 id="weblvc">WebLVC</h3>
<p>Web-based technology has become highly compelling in the last few years. Readers can confirm this by noting the degree to which the applications they use themselves today are web-based rather than compiled desktop applications. Vendors often make services available via the web rather than compiled, downloaded applications. Web applications often work across multiple operating systems and hosts with little extra work.</p>
<p>SISO runs a <a href="https://www.sisostds.org/StandardsActivities/DevelopmentGroups/WebLVCPDG.aspx">WebLVC development group</a>.</p>
<p>As the SISO group mentions, the WebLVC effort includes</p>
<blockquote>
<p>• An object-model independent section, which defines the common message headers and object-model-independent administrative messages, and defines a template for the kinds of messages that express object-model-specific data.</p>
</blockquote>
<blockquote>
<p>• A Standard WebLVC Object Model section, which defines specific AttributeUpdate and Interaction messages (expressed in the JSON format), based on the semantics of the DIS protocol and the Real-time Platform Reference (RPR) FOM. The Standard WebLVC Object Model is designed to allow a-priori interoperability between web applications, and federates that are built on these common, existing simulation standards.</p>
</blockquote>
<blockquote>
<p>• A section describing the process and rules for hand-authoring new WebLVC messages based on extended or alternative object models.</p>
</blockquote>
<blockquote>
<p>• A section describing rules for automatically generating WebLVC messages directly from an HLA FOM.</p>
</blockquote>
<p>In the end, WebLVC helps define the network messages normally sent by HLA or DIS in JSON terms. This makes network simulation network messages easy to interpret in Javascript.</p>
<p>WebLVC is interesting, but remember that it also possible to send standard DIS messages to Javascript running inside the web page. The open-dis implementation of Javascript DIS can decode the binary PDU and turn it into a Javascript object. WebLVC in some ways resembles HLA messages, however, and can send out only the attributes of objects that have changed. This means that it can often use less bandwidth in a simulation, despite using text for the message format. JSON is also highly optimized; a lot of attention is paid to it.</p>
<p>See <a href="https://jsperf.com/javascript-dis-native-vs-json/2">jsperf</a> for an interesting comparison in performance between binary messages and JSON. Still, on a laptop running a web browser it is claimed that over 50K messages per second can be decoded. That’s more than can be used in a simulation. Also, note the extend to which different webbrowsers achieve different results.</p>
<h2 id="simulation-terminology">Simulation Terminology</h2>
<p>There are a number of terms floating around in the simulation world, and that’s largely the result of the different purposes to which simulations are put. With DIS, the traditional use was what was called “virtual worlds.” Those used 3D computer graphics to display something that resembled a live video feed as closely as possible. Ideally, a viewer of the display could not tell the difference between the 3D graphics application, which displayed a collection of entities whose position and orientation was updated by DIS, and a live video pointed at a live exercise. Of course the computer graphics feed wasn’t close to solving this problem in the 1990’s, but that was the ultimate goal.</p>
<p>Over time it was realized that DIS could be used to achieve other goals. Everything from purely analytical applications of DIS, which assume that there is no graphical result intended at all, to augmented reality, which has some mix between live video and DIS-related graphics. Furthermore the simulations could include either a single user or a great many networked application elements.</p>
<h3 id="implementation-range">Implementation Range</h3>
<p>The image below shows something about how graphics are used in simulation applications, for what purpose. This primarily is related to whether 3D grahics that try to create real world appearances are generated, by how many simulation hosts.</p>
<div class="figure">
<img src="I_Introduction/images/VirtualGraphicsSpread.jpg" alt="Problem Graphics: I_Introduction/images/VirtualGraphicsSpread.jpg" />
<p class="caption">Problem Graphics: I_Introduction/images/VirtualGraphicsSpread.jpg</p>
</div>
<p>This is primarily an attempt to define the terminology used (at least by some) when related to grahics.</p>
<h4 id="analytical-no-display-single-host">Analytical, No Display, Single Host</h4>
<p>Imagine a single host that creates a description of a combat operation. The simulation is so simple that there is no attempt to use more than one host to create the simulation, and what’s more the user does not care about any graphical display of what is happening in the simulation. The traffic is instead simply saved to a database, where the combat operation is assessed after the fact, textually. There’s no effort present any display to the user. What’s more, because there is only one host generating simulaton traffic it is not particularly necessary to use one of the classic features of DIS, the conversational exchange of messages between hosts.</p>
<p>This can be thought of as the most simple simulaton example possible. The single application generates simulation operatin data, saves each message to a database, and later can play back the simulation contents. There’s no attempt to show the simulation to the users in a realistic graphics display. Instead there is perhaps some classic operations research that later assesses the saved data.</p>
<h4 id="anaylytical-multiple-hosts">Anaylytical, Multiple Hosts</h4>
<p>Very similar to a single analytical simulation generation host, but instead of one, the simulation may use several. DIS is more valuable in this scenario; multiple applications working together was an important feature from the start. As with other analytical operations, there is no attempt to use the traffic of the multiple simulation hosts to show anything graphical to the user. The simulation generally uses data operations to write messages to a database, and later reads the data back textually to analyze the simulation.</p>
<h4 id="command-and-control-graphics">Command and Control Graphics</h4>
<p>This is where it starts to become interestng. The simulation is presenting graphical results to users, but those graphics are not an attempt to create realistic displays. Instead the simulation graphics requirements may be met through displays of object or unit locations. The simulation users are satisfied if they can know the position of objects and units. Instead of a realistic display of a tank, the simulation requirements are satisified if there is a map-based display that shows the position of all the tanks in a unit, or the positions of several units. The objective is not to convince the user he is on the battlefield, but to show what the battlefield is up to.</p>
<p>An very simple display of the concept that uses the web-based Open Street Maps Javascript library is shown below. DIS messages are received from the network, and the web page shows unit locations. There is no attempt to make the unit look realistic, only make its location realistic.</p>
<div class="figure">
<img src="I_Introduction/images/MapDisDisplay.jpg" alt="Problem Graphics: _Introduction/images/MapDisDisplay.jpg" />
<p class="caption">Problem Graphics: _Introduction/images/MapDisDisplay.jpg</p>
</div>
<h4 id="virtual-single-host">Virtual, Single Host</h4>
<p>This is where the application is beginning to create graphics that are, in principle or objective, similar to a live video feed. Back in the early 90’s there was an game called “DOOM”; it had a mode in which a single application showed a 3D graphics display to the user, similar to the scene shown below.</p>
<div class="figure">
<img src="I_Introduction/images/doom-ii.jpg" alt="Problem Graphics: (I_Introduction/images/doom-ii.jpg" />
<p class="caption">Problem Graphics: (I_Introduction/images/doom-ii.jpg</p>
</div>
<p>This shows a chainsaw attack on a monster by the player. (DOOM used it’s own, message format, not DIS.) There need be no other host in the simulation. How realistic is it? For the early 90’s, not that bad! There are definitions of “virtual” in software development that include “not physically existing as such but made by software to appear to do so.” In this case DOOM was creating, for the 90’s, virtual grahical content, generated by a single host. Users were placed in graphics environments that were emotionally realistic for the era.</p>
<h4 id="networked-virtual-environment">Networked Virtual Environment</h4>
<p>This is often the environment in which DIS use crops up. While the game DOOM was often running on a single host, DIS often runs on multiple hosts. The situation can be described by the term “Networked Virtual Environment.” Any simulation may have several processes on several hosts running, some of which use 3D graphics to display a virtual world. One better than that available to DOOM in 1993. Examples of the use of Networked Virtual Environment (NVE) include the book title of Mike Zyda and Sandeep Singhal’s book, “Networked Virtual Environments: Design and Implementation.” The term is widely used in academic papers.</p>
<p>An example of a NVE (not necessarily using DIS) is below. This is an example from VR-Engage from the company <a href="https://www.mak.com/">MaK</a>.</p>
<div class="figure">
<img src="I_Introduction/images/VREngage_mak.jpg" alt="Problem Grahics: I_Introduction/images/VREngage_mak.jpg" />
<p class="caption">Problem Grahics: I_Introduction/images/VREngage_mak.jpg</p>
</div>
<p>Note that the 3D display is a bit more realistic than that of DOOM.</p>
<h4 id="augmented-reality">Augmented Reality</h4>
<p>Augmented Reality newly developing software, at least in the commercial implementation sense. Augmented reality started in research years ago, but is not on the verge of widespread commercial deployment. At this time the augmented reality applications may include offerings from Facebook or Microsoft’s HoloLens. There is also future augmented reality technology rumored to be offered from the companies Magic Leap and Apple, as well as future advances from existing vendors. Phones and other mobile devices are likely to be the platforms addressed.</p>
<p>The aspect of augmented reality that is different from virutal reality or NVEs is that it combines a live video feed with a computer-generated 3D display. A good example of the technology is, oddly enough, the game Pokemon running on an Apple iPhone. Examples are shown below:</p>
<div class="figure">
<img src="I_Introduction/images/pokemanCapture.jpg" alt="Problem Graphics: I_Introduction/images/pokemanCapture.jpg" />
<p class="caption">Problem Graphics: I_Introduction/images/pokemanCapture.jpg</p>
</div>
<p>In the Pokemon game this scene involved capture of the creature through interaction with the 3D model as it was dispalyed on the live video feed. The game proved so popular there were crowds of hundreds in popular “monster” areas. The 3D model is used as a target for capture.</p>
<p>For DoD applications one can easily imagine the 3D model of an enemy combatant that may be addressed somehow by an augmented reality application user. DoD developers are likely to supply some sort of products performing roughly this task.</p>
<h4 id="video">Video</h4>
<p>The simulation gets a live video feed. There is no input into the feed, though the source of the feed may be selected by simulation or live data.</p>
<h3 id="summary">Summary</h3>
<p>The most common application term in the DIS world is “Networked Virual Environment (NVE).” The objective of DIS is very often to have a 3D display presented to the simulation user that is virtually correct; a 3D world that is in principle identical to the real world, a <em>virtually correct</em> world. But at the same time one can’t assume DIS is unique to that. It can easily be used in an analytic simulation, or perhaps, not very long from now as the commercial market matures, a useful tool in an augmented reality simulation.</p>
<h1 id="ii.-networking">II. Networking</h1>
<h2 id="dis-networking">DIS Networking</h2>
<p>If the real time exchange of state data between distributed simulation hosts is going to be accomplished then some way of sending data between hosts over a network must be used. A form of networking called TCP/IP is the most popular way to do this.</p>
<p>Many programmers are familiar with TCP/IP, but not in the context of a distributed simulation system such as DIS. Likewise, not all system administrators are aware of what practical TCP/IP DIS networking issues exist. This topic can help DIS users understand some networking issues.</p>
<h2 id="tcpip">TCP/IP</h2>
<p>Transmission Control Protocol / Internet Protocol (TCP/IP) is a software standard that has been developed for decades and is today installed on nearly every computer.</p>
<p>TCP/IP can be a complex topic, but this tutorial will attempt to be as simple as possible. If you wish to learn more about the subject, two good books are <em>The TCP/IP Guide: A Comprehensive, Illustrated Internet Protocols Reference</em>, by Charles M. Kozierok, and <em>TCP/IP Illustrated, Volume 1: The Protocols (2nd Edition)</em>, by W. Richard Stevens. Again, that’s if want to learn more. Today there are many web sites that explain network communications over TCP/IP as well. This includes implementation libraries that make the programmer’s life easier.</p>
<h2 id="overview">Overview</h2>
<p>The illustration below shows the essentials of a four-layer interpretaton of the TCP/IP protocol.</p>
<div class="figure">
<img src="II_Networking/images/networking.jpg" alt="IMAGE TCP/IP" />
<p class="caption">IMAGE TCP/IP</p>
</div>
<p>The top layer, the Application Layer, is code simulation programmers write. It includes both code for sending and receiving DIS messages and the simulation program itself.</p>
<p>The Transport Layer and how we talk to it are the most important aspect. If lucky, we can largely ignore everything below the Transport Layer. The Application Layer is where we implement the DIS protocol and the simulatinon itself.</p>
<p>The Internet layer is responsible for changing large collections of data into smaller packets that can be routed and transmitted across the network. Very often it can be ignored by the DIS programmer.</p>
<p>The bottom layer, Network Access Layer, is related to the type of network transport used. The bottom layer may use 802.11 wireless networking, or may use gigabit Ethernet, or it may use 10 gigabit Ethernet. The interesting thing is the application can use any of these network types without changing code. An application uses the Transport Layer API, and the layers below that can use slow wireless or fast Ethernet. Our simulation application can use either.</p>
<h2 id="transport-layer-apis">Transport Layer APIs</h2>
<p>There are more than one set of features that can be used to exchange messages between hosts. These include TCP and UDP sockets, and within the UDP sockets the additional technologies of broadcast or multicast can be used as well. The API layouts are shown in the graphic below.</p>
<h3 id="tcp">TCP</h3>
<p>TCP is technology to communicate data between hosts, and it has both some advantages and disadvantages.</p>
<p>A TCP protocol networking socket is a stream-oriented connection between two hosts, and two hosts only. A single TCP socket cannot send a message to a dozen different hosts. Instead there must be a separate TCP socket from our host to each of the dozen other hosts.</p>
<p>When API to create a socket we can send a contnuous stream of data. The connection is full-duplex; messages can travel both directions between the hosts at the same time.</p>
<p>TCP sockets are responsible for transmitting reliable streams of data. This can be appealing and limiting.</p>
<p>Imagine sending a stream of hundreds of DIS Protocol Data Units (PDUs) to another host. But what happens if the network has a problem, and drops a PDU? Networks have a difficult problem delivering data reliabley. Imagine sending a copy of the Jane Austen novel <em>Pride and Prejudice</em>. Even using ASCII text, this totals over half a megabyte of data. From a practical API standpoint the programmer can send the entire text of the novel with a single command to the Transport Layer API from the Application Layer. But below the Transport Layer TCP/IP has to break up the half-megabyte of data into smaller packets. Very often the packet size used is around 1500 bytes. Each of these packets is routed through the network, and across dozens of steps. When they arrive at the destination the receiver assembles the smaller packets back into the large message sent.</p>
<p>What happens if a single smaller packet is dropped? If we are using TCP, we don’t want to lose a single sentence from a Jane Austen novel. We want a guaranteed delivery of the entire novel, undamaged. This is what TCP sockets provide. TCP will detect the loss of a packet that makes up the entire message. It will cause the sender to resend the packet, and eventually the receiver will have all the packets necessary to receive the novel. If we are sending a series of DIS PDU messages, then each PDU will be delivered.</p>
<p>TCP sockets have other features as well. TCP sockets can automatically lower or increase the speed at which they send depending on how capable the receiver is, for example. If we are sending to a slow mobile device from a fast workstation host TCP will find a usable send rate that does not overly challenge the mobile device. TCP sockets also always ensures that Austen novels are delivered in the same byte order in which they were send, and ensure that there are no dupliated bytes in the message. The end result is that the receiver gets exactly what was sent by the sender.</p>
<p>This seems attractive in many ways, but there are some limitations. First of all, notice the “one recipient per TCP socket” restriction. If we have 10 participants in a NVE, and we want all nine other participats to receive a PDU, we have to send the messsage nine times across nine TCP sockets. If we have 100 simulation participants we’d need to send the same PDU 99 times.</p>
<p>We also have to worry about <em>latency</em>, the averate time necessary to deliver a PDU from one host to another. What happens if the network somehow has a problem delivering a PDU when the network drops a packet? The TCP socket has to discover the loss of the packet after waiting long enough, and then resend it to make up for its loss. Remember TCP sockets also promise in-order delivery and reliable delivery. This means PDUs sent after the one that was lost cannot be delivered, either. The delivery of PDUs will simply stop until the lost PDU problem is fixed.</p>
<p>Do we always need a delivery of all PDUs? Not necessarily. Imagine a PDU that describes the locaton of a vehicle. A PDU that determines the location of the vehicle is sent every 1/30th of a second, about the frame rate of a 3D display. What if one of these position updates is dropped? We’d have to wait long enough to discover its loss, then ask the sender to resend it. It would also stop the delivery of the rest of the position updates. That could make the movement of the vehicle worse.</p>
<p>TCP sockets are used in NVEs for several reasons. They can be used to send DIS PDUs, though designers should note the liminations inherent in the TCP sockets. TCP can be used for other reasons as well. A TCP socket can be used to download or transmit large files, such as terrain data or graphical data when the simulation starts. For these reasons and others knowing something about TCP can be useful.</p>
<p>Rememeber, sometimes libraries that hide Transport Layer API are used, and they make the programmer’s life easier. But the fundamental limitations of using a TCP socket are not changed, and the simulation application designer has to realize this.</p>
<h3 id="user-datagram-protocol-udp">User Datagram Protocol (UDP)</h3>
<p>UDP is another API available to applications at the Ttransport Layer, just as TCP sockets are, but they deliver features that address the problems of TCP sockets addressed above. Just as the API can create TCP sockets, we also have an API that can create UDP sockets.</p>
<p>UDP sockets back off on TCP socket features. TCP sockets offer continuous streams of data. The sender and receiver remain stream connected. UDP instead sends distinct, stand-alone messages. A UDP socket will accept a message of any content and then send that message to a destination. The UDP socket does not ensure that the message is actually delivered. If the network causes its loss somewhere, there is no attempt to resend it. For an application sending a continuous stream of messages, such as the vehicle position PDUs discussed above for TCP sockets, this is good. A dropped packet will no longer halt the delivery of later PDUs.</p>
<p>UDP sockets also do not insist on delivering messages in the order they were sent. It’s possible that a PDU sent early will be delivered later. For our vehicle position reports this might seem to be a problem, but in fact it turns out to be an easy one to avoid. We can in the message contents simply include a sequence number, and drop any PDUs that are too old or out of ordor. This out of order detection is done by the Application Layer application (i.e, us) rather than the TCP socket, but it’s pretty easy to do.</p>
<p>UDP sockets back off on TCP sockets in streaming, reliable delivery, and in-order delivery. They instead deliver messages in indepenent messages, that can (but usually are not) be delivered out of order, or dropped entirely. Networks are usually reliable enough for UDP to work well.</p>
<h4 id="broadcast-udp">Broadcast UDP</h4>
<p>UDP is useful, but as with TCP sockets the initial solution is to send one message to one host. If we have 100 participants in a simulation and we want to send a message to each, we have to send 99 messages, one to each address. This takes bandwidth, bandwith use that can increase with the square of the number of participants. What we’d like to do is instead send a single message that is received by all the simulation particpants. Using broadcast addressing is one way to do this. Broadcast addresses are a special IP from early in the development of the TCP/IP protocol. Though old, it’s still used in many places. It’s less capable than the multicast protocol discussed later, but it is used by some.</p>
<p>Using broadcast uses conventional UDP sockets, but with a special approach to picking the message destination. Every host has an Internet Protocol number assigned to it. The below shows the values for a host:</p>
<div class="figure">
<img src="II_Networking/images/IPDisplay.jpg" alt="IMAGE TCP/IP" />
<p class="caption">IMAGE TCP/IP</p>
</div>
<p>As you can see, the host has an IP number of 10.0.0.158. There are no other hosts on the network with that IP. When we create a message to send to that host, we set a destination address of 10.0.0.158 in the message. If we want to send to another host, we’d have to send a new message with a different IP, such as 10.0.0.42. (Yes, you can also use a name if you are willing to convert a name to an IP, wich is usually easy to do.) If you wanted to send to 99 hosts you’d have to do this 99 times. But what if you wanted to send only one message, and have that received by everyone on that network that was interested? We can use something called broadcast addressing to do that.</p>
<p>An IP such as 10.0.0.158 actually has two parts: a network portion, and a unique host ID within that network. You’ll notice an item called the “subnet mask” that has a value of 255.255.255.0. An IP address is four bytes long, and each of the four period-sepearated numbers in the address is a separate 8-bit long byte. What is happening is that the subnet mask is defining the separating line between the “network portion of the IP” and “host withing a network” portion of the IP. In this case, because the subnet mask is using 255, it means the first three bytes are part of the network, while the last byte is used to list individual hosts. The host IP we see is 158 within our local network–there should be no other host with that IP on our network.</p>
<p>What the early designers of TCP/IP did was pick a special IP to describe “This message is for any host on the network, not just one specific host.” In the case of DIS, sending to a broadcast address would allow us to send one PDU message instead of the 99 repeated messages. That’s a valuable reduction in broadcast use. lt So what’s the special IP address? It’s the host region of the address with all bits switched on. In our case, the first three bytes (10.0.0) is the network portion. OUr host portion is set to the value 158. The broadcast address is 10.0.0.255. That’s what all bit values turned on in the host portion look like for an integer byte.</p>
<p>So long as all the simulation participants are present on same network, using broadcast can dramatically reduce the bandwidth used.</p>
<h4 id="udp-multicast">UDP Multicast</h4>
<p>Broadcast was used from early on, but in the mid-90’s a technology called multicast started to be used. Multicast is more powerful and flexible than using broadcast addressing.</p>
<p>Multicast uses UDP sockets that have been specially configured, and that use a special set of IP numbers. Any IP number in the range 224.0.0.0 to 239.255.255.255 is a “multicast address,” or group number.</p>
<p>Lets pick the multicast number 239.1.2.3, which is within the range mentioned above. We can (with a properly configured UDP socket) have a group of hosts subscribe to this address, while the rest of the hosts do not. With broadcast, <em>every</em> host on the network would be subscribed to messages sent to that address. In a network with 100 hosts, we might make only 20 subscribe to the address 239.1.2.3 for messages.</p>
<p>In our simulation application we may want to send out updates for the position of ships to other ships, and tanks to other tanks. We can set up ship applications to be subscribed to the multicast ship addres, 239.1.2.3. Any message sent to that address will be handled by hosts that have chosen to be subscribed. Likewide the tank appliations at the multicast address 239.1.2.4 will receive messages sent for tanks. The administrative application which wants to receive both tank and ship messages can subscribe to both 239.1.2.3 and 239.1.2.4.</p>
<p>Multicast is even more powerful because it is not limited to the local network. Broadcast required all the hosts to be on a single, local network. Multicat can, if configured correctly, include more than one network. For simulations, multicast networking can be used in a network that ranges across continents.</p>
<p>Multicast is the preferred solution over broadcast. Both broadcast and multicast are usually the preferred solutions over using single host addresses.</p>
<h4 id="web-based-technology">Web-Based technology</h4>
<p>This term seems a little strange, and it is. In the last few years state updates have started to be sent across web technologies. The state updates are sent across web servers. How does this happen?</p>
<p>In practice, the web servers are using TCP and UDP sockets, and the DoD applications are accessing the sockets via a higher level API. In effect this is an example of using a higher level API to access the same lower level TCP and UDP APIs. You can think of it as a supporting library, but with the added benefit of also being an officially approved international standard.</p>
<h4 id="supporting-libraries">Supporting Libraries</h4>
<p>There are in practice of lot of other APIs for accessing TCP and UDP sockets–socket creation, message transmission, message receipt, and more. There are dozens of C++ libraries. The same is true for many other languages, such as Java and Javascrpt. In practice they may hide the direct APIs presented by the operating system or TCP/IP. The libraries may occur at multiple levels of complexity, and hide the sockets discussed above at multiple levels. They may occur at someone low levels. Others may be at much higher levels, such as game engines.</p>
<p>Still, the issue is often recognizing the inherent issues among TCP. UDP, Broadcast, and Multicast sockets, not the specific programming API. Understanding the advantages and limitations of each type of underlying socket is important.</p>
<h4 id="language-specific-implementations">Language-Specific implementations</h4>
<p>Some example code that demonstates actual use of sockets is provided here. This is inherently programming language-specific–C++ code is not the same as Java code, which is not the same as Javascript code. The problem is that each language will have it’s own project code, and its own source code control site or download site. The DIS Tutorial you are reading is also maintained as a git repository, and it’s impractical to keep all the discussed data as well as all the example code in one repository–the download size alone would be impractical. In addition it wold be difficult to let multiple users add content to multiple sections.</p>
<p>Instead the tutorial maintains links to supporting source project repositories. For example, there may be dozens of example repositories for Java source code examples in projects that show use of sockets, DIS updates, or dead reckoning. There can be matching implementations in C++ or C# in different repositories.</p>
<p>That’s how the code that shows examples of how networking is used are presented here. Sections that have links to example implementations for specific languages are below.</p>
<h5 id="java-code-examples">Java Code Examples</h5>
<p><a href="II_Networking/Java_Networking_Source_Code.md">Java Networking Source Code Examples</a></p>
<h5 id="c-code-examples">C++ Code Examples</h5>
<p><a href="II_Networking/CPP_Networking_Source_Code.md">CPP Networking Source Code Examples</a></p>
<h5 id="javascript-code-examples">Javascript Code Examples</h5>
<p><a href="II_Networking/Javascript_Networking_Source_Code.md">Javascript Networking Source Code Examples</a></p>
<h2 id="summary-1">Summary</h2>
<p>This section has described some of the capabilities and problems inherent in TCP and UDP sockets, and the nature of Broadcast and Multicast approaches. Broadcast and Multicast are very useful in the DIS world. But at the same time no code of actual implementations was presented. The basic problem is that the code is language-specific. C++ code does not appear the same way that Java or Python or Javascript does. While this section can describe the general behavior, it does not provide specific code.</p>
<p>But that sort of provision is useful, and seeing actual networking programs can save a lot of time. It can also take up unreasonable amounts of disk space for users that are not immediately interested in source code, even if they eventually are. This gets even worse when you think of example projects for several languages that are inherent to an overall tutorial that is not limited to a single language.</p>
<p>Instead, the section provides a section of links to additional source code control sites. For example, a Java project using Multicast, or a Javascript project that uses web technology, or a C++ example. The repositories linked to are not directly part of this project, but can be downloaded. Read on to find links to networking implementations.</p>
<h5 id="java-networking-source-code-examples">Java Networking Source Code Examples</h5>
<p>This contains links to any source code examples for networking done in Java. Each example typically contains a link to a .md file with an explanation of what the example shows, and a link to a source code control system for the example. This lets users download detailed, well-documented, but potentially large projects for each language the reader is interested in.</p>
<h6 id="multicast-networking">Multicast Networking</h6>
<p><a href="II_Networking/Java/Java_Multicast_Networking.md">Java Networking Source Code Examples</a></p>
<h1 id="java-multicast-networking">Java Multicast Networking</h1>
<p>This is an example of using Java at a lower API level to send and receive binary data. The example code presented here uses NetBeans, a free development system available at http://netbeans.org.</p>
<p>The source code does not transmit actual DIS PDUs. Instead, only simple binary data is transmitted. The objective to to demonstrate the use of multicast sockets to transmit data, not specifically DIS. Adding DIS was thought to increase the source code used and obscure the use of sockets. Instead, only 355 lines of source are used, which makes the code purpose more understandable.</p>
<p>A single run of the application has two threads active: one thread sends data every ten seconds, and the other thread reads from the multicast socket. The sending thread writes to the socket on multicast address “239.1.2.3” and the receiver reads any messages sent to that address. One message is sent every ten seconds.</p>
<p>If the same application is run on two different hosts each will receive the messages of the other. Running on a single host the host will receive all the messages sent by that host.</p>
<p>The multicast socket can subscribe to more than one multicast address. As it stands now, it will not read messages sent to the destination address “239.1.2.100”. It could if the multicast socket performed a “joinGroup” for that address.</p>
<p>Download source code from this URL:</p>
<p><a href="https://github.com/mcgredonps/DIS_Tutorial_Multicast_Example">Source Code for Java Multicast Example</a> ##### CPP Networking Source Code Examples</p>
<p>This contains links to any source code examples for networking done in CPP. Each example typically contains a link to a .md file with an explanation of what the example shows, and a link to a source code control system for the example. This lets users download detailed, well-documented, but potentially large projects for each language the reader is interested in.</p>
<h6 id="multicast-networking-1">Multicast Networking</h6>
<p><a href="II_Networking/CPP/CPP__Multicast_Networking.md">CPP Networking Source Code Examples</a></p>
<h5 id="javascript-networking-source-code-examples">Javascript Networking Source Code Examples</h5>
<p>This contains links to any source code examples for networking done in Javascript. Each example typically contains a link to a .md file with an explanation of what the example shows, and a link to a source code control system for the example. This lets users download detailed, well-documented, but potentially large projects for each language the reader is interested in.</p>
<h6 id="multicast-networking-2">Multicast Networking</h6>
<p><a href="II_Networking/Javascript/Javascript_Multicast_Networking.md">Javascript Networking Source Code Examples</a></p>
<h2 id="iii-dis-messages">III: DIS Messages</h2>
<p>(Intro to problem)</p>
<h3 id="explaining-dis-to-readers">Explaining DIS to Readers</h3>
<p>DIS designers back in the 1980’s and 1990’s had to design a way to handle state infromation transmitted between hosts. It’s a difficult problem to solve, and one that hadn’t yet been discusseed much at the time, but they came up with a pretty good solution.</p>
<p>As has been mentioned, DIS does this with dozens of different messages, but we have not yet discussed what the messages are, or how they are used. There are two aspects to describing DIS messages: what data is present, and how the data is arranged in the message. In addition to thise we need to know how the message interacts with other messages. Consider one tank shooting at another tank. It will include information about what tank is shooting at another specific tank, and transmit that informtaion in a known format and known quantity. But we also need information about how and when the simulation creates the firing PDU, and what part of the simulation issues the detonation PDU, and when that happens. That’s information about the simulation’s DIS protocol works.</p>
<p>Describing this–both the syntax and information in the PDU, and how the PDU interacts with other messages–can be distracting. In this tutorial section it is a tricky description problem to solve. Instead we generally describes the information that’s in the message. This gives the programmer an idea about what data needs to be set or read when creating or reading a message. This section can (optionaly) also describes what this intended for in general terms and how it interacts with other messages, but tries to be general.</p>
<p>But that’s not enough in specific terms. In addition to this section, it’s valuable to also look at the approach used in Section IV, which expands on the use of DIS traffic when implementing a specific task in compliance with the standard. For example, creating an entity, or one vehicle shooting at another. This gives more details on using DIS to accomplish a solution.</p>
<p>At the same time, this tutorial is not about how to write an implementation of DIS. It helps, but in the end, anyone writing their own implemntation of the PDUs they are using. That involves acquiring a copy of the IEEE-1278 standard, which has creater detail about individual fields and where they are placed in messages. In the end, our interpretation will be less accurate than the defining IEEE-1278 standard itself, and you should read the source document.</p>
<h3 id="byte-order">Byte Order</h3>
<p>Byte order. Yeesh.</p>
<p>DIS sends information in binary format between hosts. Those hosts may have CPUs from any of many vendors, and CPU makers have made different choices about how to represent numbers that take more than one byte to represent. An “integer,” for example, often is represented with 4 bytes. But the question is, does the byte farthest to the left have the highest value, or the byte farthest to the right? This seems odd, but the CPU vendors made different choices for decades. The TCP/IP protocol largely chose to do “big endian” arrangement for multi-byte numbers. In fact, it happens so often that “big endian” is sometimes called “network byte order.” But the Intel CPUs and, today, several other CPUS choose to use “little endia” multibyte numbers.</p>
<p>For details on big vs. little endian, see https://en.wikipedia.org/wiki/Endianness</p>
<p>DIS sends many multi-byte data fields such as short integers, full integers, floating point numbers, and double precision floating point numbers. From a programming operation standpoint one danger is to write your own DIS code, read a PDU, and then incorrectly decode the DIS message as little endian binary data. This will cause very strange results, because the field values will be translated to values far away from reality.</p>
<p>This is often not as bad as it may seem for programmers. They often use pre-existing libraries that hide the byte order within a higher level API; in the case of DIS, there are almost always implementations that take care of endianess issues themselves. However, implementators of DIS simulations sometimes write their own DIS implementations, and they need to be aware of the issue. Those who choose to log messages to storage may need to be aware of byte order captures as well. Some PDUs include the ability to include simulation-generated data in binary format as well, and this is often set to big-endian format, while some others use little-endian format. If anything goes wrong with transmitted user data you should check the endian format used on both sides.</p>
<p>In the end, be aware of the possiblity of error when you create a DIS message and then put it onto the network. There’s a possibility that it will be placed onto the network in the wrong byte order.</p>
<h3 id="languages-and-implementations">Languages and Implementations</h3>
<p>What’s standardized in DIS is the messages placed on the network, not an API, or for that matter languages at all. Where HLA has standardized APIs for Java and C++, DIS can be implementated in Python, Javascript, C++, Objective-C, C#, or any other language that can read and write binary code. Even within C++ there can be different APIs in the implementation.</p>
<p>To compare two open source implementations in the , consider KDIS (https://sourceforge.net/projects/kdis/) and Open-DIS (https://github.com/open-dis/open-dis-cpp) and their API implementatons of one of an Entity State PDU, one of the most used PDUs. Both implementations have slightly different code to do exactly the same thing, in this case setting a number in an object that identifies what type of PDU message this is. In the case of KDIS, it looks like this:</p>
<pre><code>//************************************
// FullName:    KDIS::PDU::Header6::SetPDUType
//              KDIS::PDU::Header6::GetPDUType
// Description: The type of PDU. Set by PDU automatically.
//              Only change if you know what you are doing.
// Parameter:   PDUType Type
//************************************
void SetPDUType( KDIS::DATA_TYPE::ENUMS::PDUType Type );
KDIS::DATA_TYPE::ENUMS::PDUType GetPDUType() const;</code></pre>
<p>On the other hand, the Open-DIS C++ source code for gettng and settin the PDU type in any PDU looks like this:</p>
<pre><code>unsigned char getPduType() const; 
void setPduType(unsigned char pX); </code></pre>
<p>The function name for setting the pdu type is not the same–one uses a capital letters in places the other does not, to begin with. That means changing a C++ simulation to use Open-DIS rather than KDIS is likely to involve considerable work to change the simulation code. The function calls in the code would need to change, at least, and it would likely involve many other changes to the code logic.</p>
<p>Likewise, a the API changes between languages. The Open-DIS Python language implementation of DIS relies on the programmer directly accessing the pduType data field of PDU object instead of using an accessor method:</p>
<pre><code>self.pduType = 1</code></pre>
<p>As does the Open-DIS Javascript implementation. The direct access (arguably) follows some of the Python and Javascript language writing habits, while C++ and Java typically use access methods to set or retrieve field values. The Java Open-DIS implementation relies on the “getPduType()” and “setPduType()” methods and the habits of the Java language. There is no standard at all for the names of the API functions to set the value–any method name at all is legitimate, and any popular language implementation can be used in any language capable of reading and writing binary data to the network.</p>
<h3 id="list-of-all-pdus">List of All PDUs</h3>
<p>A display showing the complete list of PDUs is shown below.</p>
<div class="figure">
<img src="III_DIS_Messages/images/pduHierarchy.jpg" alt="Alt text" />
<p class="caption">Alt text</p>
</div>
<p>Notice the “inheritance”-style structure of PDUs.</p>
<p>If you’re planning on writing an implemetation of DIS the information in this section is not enough. If you want to do that you should acquire a copy of the IEEE-1278 document. The information in that standards document has the required information, and it is unrealistic to duplicate it here. It does give some idea about what information is in the various PDUs, and what they are used for.</p>
<h3 id="pdu-header">PDU Header</h3>
<p>Every one of the PDUs in DIS starts with the same fields. You can think of it as a superclass and that all PDUs inherit those data fields.</p>
<table>
<thead>
<tr class="header">
<th>Field Name</th>
<th>Data Type</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Protocol Version</td>
<td>8 bit enumeration</td>
</tr>
<tr class="even">
<td>Exercise ID</td>
<td>8 bit unsigned int</td>
</tr>
<tr class="odd">
<td>PDU Type</td>
<td>8 bit enumeration</td>
</tr>
<tr class="even">
<td>Protocol Family</td>
<td>8 bit enumeration</td>
</tr>
<tr class="odd">
<td>Timestamp</td>
<td>32 bit unsigned integer</td>
</tr>
<tr class="even">
<td>Length</td>
<td>16 bit unsigned integer</td>
</tr>
<tr class="odd">
<td>PDU Status</td>
<td>8 bit record</td>
</tr>
<tr class="even">
<td>Padding</td>
<td>8 bits unused</td>
</tr>
</tbody>
</table>
<p>This fields are at the start of every one of the dozens of PDUs, and the values inside these fields vary. An Entity State PDU will always have a “pdu type” field value of 1, and that lets a binary-reading application identify the type of PDU that just arrived.</p>
<h4 id="protocol-version">Protocol Version</h4>
<p>As with many software implementations new and updated software is sometimes released. In the case of DIS, there are typically three versions of DIS that some implementations use.</p>
<p>DIS Protocol Version 5 is is a IEEE standard of DIS introduced in 1995. The binary value for 5 is placed in the field. Version 5 is somewhat rarely seen in lab applications.</p>
<p>DIS Protocol Version 6 was introduced by a later IEEE version in 1998. It corrected some ambiguous or incorrect implementations of DIS. It is likely the most seen version of DIS used in applications.</p>
<p>DIS Protocol Version 7 was approved by SISO and IEEE in 2012. It introduced some new PDUs related to energy emissions for military action.</p>
<p>This information can be important. DIS versions are typically backward-compatible, but not always forward-compatible. Version 7 implementations can usually handle version 6 messages, but version 6 and be confused by new messages sent by version 7 energy emission PDUs.</p>
<h4 id="exercise-id">Exercise ID</h4>
<p>on any given network there may be multiple copies of a simulation running. Perhaps a single given application may have five copies running on the same network. This can introduce confusion, and we would want some way for the first copy to distinguish itself from copies two, three, four, and five. This is what the Exercise ID and do. When we start the application we can specify a unique number for that copy of the simulation.</p>
<h4 id="pdu-type">PDU Type</h4>
<p>Every type of PDU (see below) in DIS has a different number assigned to it. The Entity State PDU has a value of 1 in this field, for example. Simulations that receive a binary format PDU can peak at this binary field, decode the value, and then parse the rest of the PDU accordingly. Once we decode the value we know what we need to do to decode the rest of the PDU.</p>
<h4 id="timestamp">Timestamp</h4>
<p>The Timestamp field relates to when the PDU was sent. It’s a 32 bit field, and the subject is complex. It can be used to determine which PDU was sent first; if send via UDP networks, the PDUs might not arrive in the same order they were sent. There are two versions of time saved, one based on absolute time values, and another based on the sender’s local clock time. The field itself represents units of time that have passed since the start of the hour, which means that the value of the field will drop at the start of the hour.</p>
<p>The timestamp field is discussed in greater depth elsewhere.</p>
<h4 id="length">Length</h4>
<p>Some PDUs are of variable length. The length field tells us exactly how long the PDU is. In some cases network packets contain several PDUs; knowing the exact length of each PDU in the packet helps us decode the entire set of several PDUs.</p>
<h4 id="pdu-status">PDU Status</h4>
<p>This is also a somewhat complex topic that needs more space to explain. The PDU Status field contains bit areas that can be extracted to reveal more information about the PDU, and how it relates to other traffic.</p>
<h4 id="padding">Padding</h4>
<p>The PDU header was originally sent with 16 bits of unused space. This was intended to allow some later expansions of headers and cause few problems in backward compatibility. DIS version 7 used 8 of the original 16 bits to implement the PDU Status field, and there are 8 bits that are still unused.</p>
<p>Remember, all PDUs start with the same set of fields listed above. There is a free utility called WireShark (https://www.wireshark.org/) that can be used to capture network traffic and decode the PDU fields, including the PDU header fields.</p>
<h2 id="entity-families">Entity Families</h2>
<h3 id="entity-information-family">Entity Information Family</h3>
<p>The Entity Information Family is a group of PDUs that are related to that of the position and other information about entties. They describe the location of entities, and sometimes their collision. An image of the PDUs in the family is below.</p>
<div class="figure">
<img src="III_DIS_Messages/images/EntityInformationFamilyPdus.jpg" alt="Alt text" />
<p class="caption">Alt text</p>
</div>
<h4 id="entity-state-pdu">Entity State PDU</h4>
<p>The entity state PDU is one of the most widely used PDUs in DIS. It includes the unique ID of the entity described, numeric values that describe the type of entity, and its position, orientation, velocity, acceleration, and the dead reckoning algorithm that should be used between the receipt of other position PDUs.</p>
<p>Describing what the Entity State PDU (ESPDU) does can be complicated or simple. Some of the capabilities are described in greater detail elsehwere in this document.</p>
<p>The Java language class documentation for the ESPDU class is available here.</p>
<h5 id="pdu-header-1">PDU header</h5>
<p>Every ESPDU starts with the PDU header, just as does every other PDU.</p>
<h5 id="enity-id">Enity ID</h5>
<p>Every entity handled by DIS–every vehicle, every person whose position is described, every ship, every aircraft–must have an ID to uniquely identify it. This is what the entity ID is. It is described later, butiIt consists of a triplet of three numeric values: {Site, Application, Entity}. The triplet, together, must be unique. Arriving ESPDUs decode the entity ID and use it to update the position and orientation of the entity it is tracking.</p>
<p>Entity ID is discussed in greater depth in Section IV: <a href="../IV_DIS_Issues/EntityIdentifiers.md">Enity Identifiers</a></p>
<h5 id="force-id">Force ID</h5>
<p>There can be more than one (or two!) force affiliations on the battlefield. The force ID field lets you specify this. The values set are defined in the Enumerated and Bit Encoded Values (EBV) document published by SISO. This document contains many pre-defned values. This is the case for force ID fields, as shown below:</p>
<table>
<thead>
<tr class="header">
<th>Force</th>
<th>Integer Field Value</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Other</td>
<td>0</td>
</tr>
<tr class="even">
<td>Friendly</td>
<td>1</td>
</tr>
<tr class="odd">
<td>Opposing</td>
<td>2</td>
</tr>
<tr class="even">
<td>Neutral</td>
<td>3</td>
</tr>
</tbody>
</table>
<h5 id="number-of-variable-parameters">Number of Variable Parameters</h5>
<p>The ESPDU can also contain some extra parameters with arbitary, programmer-defined data. This field identifes the number of the parameters (which are of a pre-defined size) at the end of the PDU. This is descrbied in greater detail later in the document.</p>
<h5 id="entity-type">Entity type</h5>
<p>One question is how the receiver should draw the entity. How does the simulation know what it looks like? The type of the entity being described is included in the entity type field of the ESPDU. The receiving simulation can identify the entity type and, if it has a model for the entity, use that model to draw on the screen.</p>
<table style="width:28%;">
<colgroup>
<col width="18%" />
<col width="9%" />
</colgroup>
<thead>
<tr class="header">
<th>Field Name</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Entity Kind</td>
<td>The kind of entity described by the Entity Type record</td>
</tr>
<tr class="even">
<td>Domain</td>
<td>The domain in which the entity operates (e.g., subsurface, surface, and land) except for munition entities</td>
</tr>
<tr class="odd">
<td>Country</td>
<td>Nation to which the entity belongs</td>
</tr>
<tr class="even">
<td>Categroy</td>
<td>Unique ID</td>
</tr>
<tr class="odd">
<td>Subcategor</td>
<td>Unique ID</td>
</tr>
<tr class="even">
<td>Specific</td>
<td>Unique ID</td>
</tr>
<tr class="odd">
<td>Extra</td>
<td>Unqiue ID</td>
</tr>
</tbody>
</table>
<p>The EBV document includes SISO-defined collections of entity types. For example, the UK Challenger Main Battle tank has these values:</p>
<table>
<thead>
<tr class="header">
<th>Field Name</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Entity Kind</td>
<td>1</td>
</tr>
<tr class="even">
<td>Domain</td>
<td>1 (land)</td>
</tr>
<tr class="odd">
<td>Country</td>
<td>223 (UK)</td>
</tr>
<tr class="even">
<td>Categroy</td>
<td>1</td>
</tr>
<tr class="odd">
<td>Subcategor</td>
<td>2</td>
</tr>
<tr class="even">
<td>Specific</td>
<td>2 (Mk 2)</td>
</tr>
<tr class="odd">
<td>Extra</td>
<td>Unused</td>
</tr>
</tbody>
</table>
<p>This information was defined in the EBV SISO document, and is an agreed-upon, compact, and exact vocabulary for defining entity types.</p>
<h5 id="alternate-entity-type">Alternate Entity Type</h5>
<p>This is exactly like an Entity Type field. However, some simulation applications also want to allow simulations to use deceptive appearances to other simulations. If an aircraft issues deceptive electronic signatures to make a fighter aircraft appear to be a civilian airliner, that is possible. The alternate entity type field holds a description of what airliner that entity is, and other simulations may present an airliner in the 3D display, rather than an F-16.</p>
<h5 id="entity-linear-velocity">Entity Linear Velocity</h5>
<p>How fast the entity is moving. Three coordinate values (x, y, and z) are used. This is quite valuable for making the entity appear to travel in a smooth manner by using dead reckoning to move the entity between receptions of individual ESPDUs, which might appear only seconds apart. We don’t want the movement to appear to be jerky or hyperspace-jump like.</p>
<p>The coordinate system used in the field varies. It could be global, with a coordinate system that has its origin at the center of the earth, or it may use a more local coordinate system. The type of coordinate system used in the field is set in the dead reckoning field below.</p>
<h5 id="entity-location">Entity Location</h5>
<p>The entity location is interesting. It uses a three-value record, X, Y, and Z, that measures the distance from the center of earth. These values can be converted to latitude, longitude, and altitude with some mathematical work, or to MGRS coordinates, or to a local coordinate system placed with its origin at a known location. It is described further in a later section.</p>
<p>Entity Location is dicussed in more detail at <a href="../IV_DIS_Issues/CoordinateSystems.md">Entity Location</a></p>
<h5 id="entity-orientation">Entity orientation</h5>
<p>This determines which way the entity is pointing. It’s a little mysterious; what defines the “front” or “up” of an entity? Still, it can often be defned. As with the location, this is described elsewhere, but is done with what are called “euler angless.”</p>
<h5 id="entity-appearances">Entity appearances</h5>
<p>Some entityeis may be burning, or smoking, and this alters how receiving simulations should draw the entity. There are several appearance settings, and this is accomplished in the ESPDU by using a 32-bit integer. Sub-regions of the integer are used to describe the appearnce.</p>
<h5 id="dead-reckoning-parameters">Dead Reckoning Parameters</h5>
<p>This represents how the sending simulation believes dead reckoning should be done. For example, should it include the entity’s acceleration, or not. The angular acceleration, or not? The object’s linear acceleration, or not?</p>
<p>This is another subject discussed elsewhere. (Sigh.)</p>
<h5 id="entity-marking">Entity Marking</h5>
<p>This is a useful debugging measure. The marking is effectively 11 string characters. This lets presenting applications use thestring to hae a small description drawn along with the 3D model. Viewers can view something like “Open-DISApp” or “FooApp”.</p>
<h5 id="capabilities">Capabilities</h5>
<p>A 32-bit integer. Subranges of the integer describe what the entity is capable of.</p>
<h5 id="variable-parameters">Variable Parameters</h5>
<p>The ESPDU can contain a list of variable paramters. Each of the paramters is 128 bits, total, long. This can be used to contan such information as the direction in which the rotating turent of a tank is pointing, and what the elevation of the gun is. This deends on the sending and receiving simulations having an agreement on what the variable paramters mean, and what the endian format of the data is in.</p>
<h4 id="collision-pdu">Collision PDU</h4>
<h4 id="collision-elastic-pdu">Collision-Elastic PDU</h4>
<h4 id="entity-state-update-pdu">Entity State Update PDU</h4>
<h4 id="attribute-pdu">Attribute PDU</h4>
<h3 id="warfare-protocol-family">Warfare Protocol Family</h3>
<h4 id="firing-pdu">Firing PDU</h4>
<h4 id="detonation-pdud">Detonation PDUD</h4>
<h4 id="directed-energy-pdu">Directed Energy PDU</h4>
<h4 id="entity-damage-status-pdu">Entity Damage Status PDU</h4>
<h2 id="iv-dis-aspects">IV: DIS Aspects</h2>
<p>The description of PDUs in “DIS Messages” (Section III) was somewhat general. For example it pointed out that the Entity State PDU had coordinates that defined the position of the entity it described, but did not specify what the process was for converting the numbers into an actual position. Likewise for which way the entity pointed, or how to dead reckon the position of an entity between the arrivals of ESPDUs.</p>
<p>The prior section gave you an idea of what was contained in a PDU, but not how to use the field values to accomplish something, or what the assumptions were. This section is a long list of tasks, and how to do them.</p>
<h3 id="entity-id">Entity ID</h3>
<h3 id="position">Position</h3>
<h2 id="entity-identifiers">Entity Identifiers</h2>
<p>A simulation may have hundreds or even thousands of entities in one simulation world. As a practical matter we need a way to uniquely identify every entity in the world, and before we can inform an entity that its position has been updated we need a way to uniquely identify the entity.</p>
<p>The Entity ID structure is used in many PDUs, any that must be used to modify or retrieve data from an entity. The ESPDU message contains a entity ID that describes the state of an entity, including its position. Being able to match the position of an entity in the DIS simulation based on the entity ID is critical. The same for entities being shot at in the combat PDUs.</p>
<p>When DIS was designed a goal was for it to not have a central server. Simulations had to work out identifier issues among themselves in a distributed technique, and not by contacting a single server guaranteed to hand out a single, unique number that must be unique.</p>
<p>The solution landed upon was to use a collection of three unsigned shorts that would, together, uniquely identify an entity. These three numbers are the site ID, application ID, and entity ID.</p>
<p>The simulation manager can during the planning phase assign identifiers for the site and application. For example, the simulation manager can specify these values for sites:</p>
<table>
<thead>
<tr class="header">
<th>Site</th>
<th>ID</th>
<th></th>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Norfolk</td>
<td>17</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td>29 Palms</td>
<td>23</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="odd">
<td>China Lake</td>
<td>42</td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>The numbers are arbitrary, but need to be agreed upon by all simulation participants. At a range of 1 to 65,535 the number of sites can be quite large and uncrowded. (Zero for a field value is prohibited to distinguish it from a default or unset value.) The running simulation organizers specify what the values are. It’s helpful to have values picked to match up with prior simulations; in other words, try not to change the DIS site value for China Lake every simulation, and see if it can be kept stable. Simulation variants are common enough that a single number can’t be assumed, though.</p>
<p>Likewise, the simulation manager can define some arbitrary values for applications:</p>
<table>
<thead>
<tr class="header">
<th>Application</th>
<th>ID</th>
<th></th>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>JCATS</td>
<td>82</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td>OneSAF</td>
<td>1337</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="odd">
<td>VBS3</td>
<td>101</td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>As with the site ID, there is a lot of data space. Even in large simulations there may only be a couple dozen applicatons in a 64K space.</p>
<p>The final value of the Entity ID triplet is the entity value.</p>
<p>For example, a JCATS simulation at Norfolk that creates an entity may have an entity ID of (17, 82, 4576). A VBS3 simulator at China Lake may have an entity ID of (42, 101, 8472).</p>
<p>This algorithm minimizes the conflicts that may occur. Instead of selecting from a large, single ID space, simulations only need to deconflict IDs at a single site, within a single application. VBS3 does not have to communicate with OneSAF at all, nor JCATS with OneSAF anywhere. Likewise, OneSAF clients at 29 Palms need not communicate with OneSAF clients at China Lake when chosing a unique Entity ID. The only possible need for communication is multiple applications from the same vendor at the same site.</p>
<p>The final value of the triplet, the entity number, is often selected randomly within the range of 1 to the maximum unsigned short value, 65,535. Often simply a random selection from such a large ID space is good enough to prevent conflicts. More careful and better programmers can check to see if that entity ID has already been selected by another application at that site by looking at the IDs of messages already received and processed. There’s a very small risk of conflict due to race conditions, but that seems like a low risk. A more complex solution is to write an application that provides a single server for that application at that site.</p>
<p>The algorithm described above relies in part on consistent application of site and application IDs. For a single application at a single site, such as VBS3 at China Lake, coordinating site and application IDs is not as important, and these numbers can be configured in the application.</p>
<p>The Entity ID design also has useful aspects. It is straightforward to eliminated all entities from China Lake; just ignore any PDU with a site ID of 42, for example. Or one can ignore all entities generated by an aircraft simulator in a tank application by not handling any entities generated by the aircraft simulators</p>
<p>At the time DIS was designed servers were still exotic software. In this day and age it is trivially easy to set up a web server that can provide the service of handing out unique IDs. A designer replicating DIS today would almost certainly choose this technique, but the installed base is what it is. The “no-server” philosophy of DIS does still have some benefits for interoperability. For small, simple simulations the odds are that a working interoperable simulation can be created out of the box without a server are good.</p>
<h3 id="coordinate-systems">Coordinate Systems</h3>
<p>DIS is transmitting state information about entities in the world, and the most important state information is usually where the entities are and which direction they’re pointing-their position in the world. This brings up an obvious but important question: what coordinate system should we use to describe an entity’s location? It’s a trickier question than one might think at first. There’s a simple solution that can be used in games, but that doesn’t work well with real world position data. There’s a much more complex answer that can be used to describe the position of items in the real world, but even that solution has a series of problems.</p>
<h4 id="game-coordinate-systems">Game Coordinate Systems</h4>
<p>The technology that games are similar to what the military simulation applications use, and the solution games apply to the coordinate system problem can illustrate a few things. First person like Call of Duty, World of Warcraft or Skyrim move entities in 3D worlds, just as military simulations do. The games use a 3D graphics library to position and render entities, perhaps OpenGL, Direct3D, Web3D, or the higher level higher game engine graphics such as OpenSimulator, Lumberyard, or Unreal. The graphics package has to use a master coordinate system to position entities and then draw them. Figure x is a screen capture from the Blender 3D tool that shows the simplest possible situation: a cube that’s offset a few units from the universal coordinate system’s origin. The overall coordinate system origin is at the intersection of the blue and red lines, and the cube has an additional, local coordinate system set at its center.</p>
<p><img src="images/coordinateSystem/rectilinearPosition.jpeg"/> Figure x</p>
<p>At this point the “what coordinate system?” question seems to have a simple answer. Simplicity is a virtue in programming, so we’ll describe the game world using a coordinate system that assumes the world is infinitely flat in all directions. World of Warcraft can lay out the villages and roads used in their world on a surface that’s flat, and we’ll pick a Cartesian master coordinate system that can be used to describe the position of everything. We’ll pick a place to put the origin, and then we can describe the position of any feature in the world fairly directly. This makes the math involved not so bad.</p>
<p>We can also use other coordinate systems that are helpful for an player. A game engine used by a player viewing the game from a street in the village of Goldshire might find it helpful for there to be a local coordinate system with a nearby origin. See figure x.</p>
<p><img src="images/coordinateSystem/multipleCoordinateAxes.jpg"/> Figure x</p>
<p>There’s a master, global coordinate system, but we can also set up other coordinate systems because this usually makes various programming tasks simpler. There’s some math involved to express a new coordinate system in terms of the master coordinate system, but it’s not all that bad. If you didn’t sleep through the linear algebra class you can probably pull it off.</p>
<h4 id="real-world-coordinate-systems">Real World Coordinate Systems</h4>
<p>We have a less pleasant situation when we’re trying to describe the position of entities in the real world.</p>
<p>Entities are positioned on the earth’s ellipsoid-shaped surface, and that’s even worse than using a perfectly round sphere. If we’re trying to realistically model naval warfare then we won’t be able to see a ship 100 km away from our ship because it’s below the horizon. Using a single, unified, flat coordinate system would not be realistic and if the exercise is conducted across a large geographic scale it wouldn’t provide good training. The gamer’s admirably simple approach of using a flat coordinate system for a flat world doesn’t work because the real world isn’t flat.</p>
<p>There are other problems. In an LVC environment, we’re trying to pull together information from multiple sources. The location of buildings or roads is provided by maps, and the maps are often using latitude and longitude to describe their positions. These days there are petabytes of open source information on the web that’s georeferenced, from coffee shop locations and roads to tribal cultural information. The positions are also usually described in latitude and longitude. The Army often uses Military Grid Reference System (MGRS) to describe the position of units. And, as mentioned above, we’ve got a game graphics package which we’re also using to describe the position of entities, and the graphics system coordinate system is Cartesian. We may also be trying to describe the orbit of a satellite, or the relative positions of five maneuvering aircraft.</p>
<p>Imagine a virtual vehicle driving through a town. The vehicle is being rendered in a game engine that’s using a conventional Cartestian coordinate system that is flat and rectilinear. We’re using the web as a source of position data for real items in the world, and as anyone who has used Google Maps can attest those positions are almost always described in terms of latitude, longitude, and altitude. We want to be able to look up while inside the game and see the position of a constructively simulated satellite overhead, and the position of that satellite’s orbit may be described using Keplerian orbital elements. We also want to arrive at a destination that’s specified in MGRS. At the same time we are shot at by a simulated artillery fire system that’s 30 KM away, so the curvature of the earth can’t be ignored.</p>
<p>We’re trying to integrate positions of entities that are described by multiple coordinate systems and the organizations that describe the position of things in the world don’t know or care what our simulation is using as a coordinate system. The system World of Warcraft uses–a flat, rectilinear coordinate system for their entire game world–falls apart when it is integrated with data that comes from an ellipsoid-shaped world. (At least if you’re not a member of the <a href="https://theflatearthsociety.org/home/">Flat Earth Society</a>.)</p>
<p>So what coordinate system should be used by simulations to integrate all these data sources, while also making game graphics workable?</p>
<p>DIS is used in many domains, including sea, subsurface, air, land, and space. If the simulation’s geographic extent is large enough the curvature of the earth can’t be ignored. A simulation limited to land operations might choose MGRS, but this does not work well for aircraft simulations, where we usually want to do physics calculations in a rectilinear system. Naval operations might choose latitude/longitude, but this does not work well for air operations or space operations. We should also settle on either metric or English units. These goals are in conflict with each other, and some tradeoffs have to be made.</p>
<p>DIS chose to use a Cartesian coordinate system with its origin at the center of the earth, and to use meters as the unit of measurement. The X-axis of this coordinate system points out from the center of the earth and intersects the surface of the earth at the equator and prime meridian. The Y-axis likewise intersects the earth’s surface at the equator, but at 90 degrees east longitude. The Z-axis points up through the north pole. This coordinate system rotates with the earth; it is sometimes called “Earth-Centered, Earth-Fixed” (ECEF).</p>
<p><img src="images/coordinateSystem/DISCoordinateSystem.jpg"/></p>
<p>This gives us a rectilinear coordinate system with an origin at the center of the earth. With some math (described later) we can now position an entity on the surface of the earth. The World of Warcraft solution is admirably simple but not realistic, while the DIS coordinate system and description of the world is more complex, but more useful.</p>
<p>It seems like an odd choice at first glance. The geocentric coordinate system is, in isolation, not very convenient. Suppose we want to move an entity on the surface of the earth one meter northwest. How much do we change the values of the X, Y, and Z axes in the geocentric coordinate system to accomplish this in our simulation? That’s not intuitively obvious. The key caveat is that the position of entities described in this DIS coordinate system are only need to be used when a state update is <em>sent on the network</em>. Our simulation can use whatever coordinate system it likes internally, but must transmit its entity positions to other simulations using the geocentric coordinate system. What we need is a way to convert to and from our internal coordinate system to the global geocentric coordinate system.</p>
<p>The advantage of using a geocentric coordinate system is that, with some math, we can convert it to and from other popular coordinate systems. There are equations to convert from a position described with latitude, longitude, and altitude to the geocentric coordinate system and back again. The same for the DIS coordinate system and MGRS. The approach DIS uses to to allow simulations to use any coordinate system they like internally–whatever that simulation feels is convenient–but when transmitting state information on the network, convert from that coordinate system to the DIS geocentric coordinate system. Likewise, when we receive a state update that describes the location of an entity, we have to convert from the geocentric coordinate system to whatever coordinate system we use internally. What is needed to pull this off is the math to convert between the coordinate system of convenience and the DIS geocentric coordinate system.</p>
<h4 id="datums">Datums</h4>
<p>This is where it starts to get really tricky, at least for me. The geocentric coordinate system is OK, but where is the surface of the earth? The geocentric coordinate system by itself doesn’t describe that. We also need a mathematical model for what the shape of the earth is. Modeling the earth as a perfectly round sphere will run into problems.</p>
<h3 id="position-1">Position</h3>
<p>Most simulations use a local, rectilinear coordinate system for physics and for drawing nearby entities, very similar to what World of Warcraft does. They describe and draw the position of nearby entities using a flat coordinate system. Then, before sending the position of the entity to the network, the simulation converts it from the local coordinate system to the global, geocentric coordinate system. The math to do these operations is well-understood and efficient.</p>
<p>For example, a simulation might find it convenient to set up a local, flat, rectilinear coordinate system with its origin at a given latitude, longitude, and altitude, tangent to the surface of the earth.</p>
<p><img src="images/coordinateSystem/LocalCoordinateSystem.jpg"/></p>
<p>This coordinate system is rectilinear and doesn’t take into account the curvature of the earth, but for most simulation purposes it works when entities are within a few kilometers of each other. More importantly, for the most part it’s mathematically tractable, and easy to work with in the context of most graphics and physics packages. We can make the local simulation’s coordinate system co-extensive with the graphics package coordinate system. If we’re using a 3D graphics system like Unity or X3D we can make the graphics system coordinate system match that of the tangent plane we set up. We can easily move an entity one meter along the X-axis in the local coordinate system. When we describe the position of the entity to other simulations by sending a PDU, called the Entity State PDU (ESPDU), we convert the position of the entity from the local coordinate system to the global, geocentric coordinate system.</p>
<p>Many simulations use a East, North, Up (ENU) mapping convention for the local coordinate system axes, with east along the X-axis, north along the Y-axis, and Z pointing up from the surface of the earth. There’s not much agreement on which way the coordinate axes point, though. Another popular convention is NED, north, east, down for X, Y, and Z. Aircraft often use a local coordinate system that puts the origin at the CG of the aircraft, with the X-axis pointing out the nose, the Y-axis out the right wing, and the Z-axis pointing down. Then the position and orientation of the aircraft are described in the context of another local coordinate system. The position of a weapon on the wing of the aircraft needs to undergo several conversions, from the aircraft-centric coordinate system, to the local coordinate system that describes the position of the aircraft, and from there to the geocentric coordinate system. These conventions can be accommodated with enough math.</p>
<p><img src="images/CoordinateSystemTransformation.jpg"/></p>
<p>In this example the position of a tank entity is described in several different coordinate systems. In the local coordinate system–the coordinate system used for most physics and graphics–it’s at (10, 10, 4), and that local coordinate system has its origin at latitude 43.21, longitude 78.12, at an altitude 120 meters above the geoid described by WGS-84. In geodetic coordinates the tank is at latitude 43.21, longitude 78.12 (plus a little for both, to reflect the offset from the origin) and altitude 124. In UTM it’s zone 44N, 266061E, 44788172N, 124m. In DIS coordinates it’s at (958506, 455637, 4344627). Each of the positions describes the same point in space using different coordinate systems, and we can (with enough math) translate between them.</p>
<p>DIS simulations usually do all their local physics calculations and graphics displays in a local coordinate system which has been picked for the programmer’s convenience. When the ESPDU is being prepared to be sent the position of the entity in the local coordinate system is transformed to the DIS global coordinate system, and then set in the ESPDU. When received by the simulation on the other side, that simulation translates from the global coordinate system to whatever its own local coordinate system is.</p>
<h3 id="coordinate-system-standards-problems">Coordinate System Standards Problems</h3>
<p>There are a few wrinkles in this. While the geocentric coordinate system origin is placed at the center of the earth, the coordinate system does not by itself define where the surface of the earth is. The earth is not a sphere, but rather a somewhat flattened egg-shaped surface. There are several mathematical models, called “datums,” used to describe what the shape of the earth is, usually in the form of an oblate spheriod. Today the most popular of these is called WGS-84, which is also the model for the shape of the earth used in GPS. It’s not exact; the real world’s mean sea level can differ from the geoid defined by WGS-84 by 0-5 meters. That may not sound like much when working on a planetary scale, but simulations that are modeling kinetic weapons require high precision for entity locations. A shot by a cannon that’s off by two meters may be a clear miss.</p>
<p>Some maps use datums other than WGS-84 for the shape of the earth. The Australians use a datum called GDA-94 on their maps because that works well for modeling the layout of land in Australia, and that replaced an earlier datum called AGD-84. Historically the Japanese and Indians have also used their own datums for mapping, as have many nations, and even states within the US. The datums they chose often predate the creation of WGS-84 and GPS, and were picked because they tend to work well for the region of the earth that the map describes. Datums have been argued about for centuries, and after many decades of map publishing it’s quite easy to come across a map that does not use WGS-84. Even though the US government has a National Geospatial Intelligence Agency responsible for mapping, the fact is that LVC simulations often use maps or geo-referenced entities from many non-government sources that use different map datums.</p>
<p>The problem is that using different datums also causes the models for the shape of the earth to differ. Imagine a single entity that has its position described as being 36.5973° N, 121.8731° W. The latitude and longitude lines are fixed to the surface of the earth model, and two maps are using different datums. See what can result in figure X. The datums describe two different 3D surfaces. An entity described with the same latitude and longitude will be in two different locations in 3D space. Their locations depend on the datum the map uses in addition to the reported latitude and longitude.</p>
<p>Figure X. (two curves, describe a surface. same lat/lon, different 3D positions.)</p>
<p>How big of a deal is this? Some of the datums described above could result in a difference of up to 200 m from WGS-84. If you place a map that uses one of those datums into an environment that assumes WGS-84 you’ll see terrain feature discrepancies even though latitude and longitude for the feature are identical on the two maps. There may be differences of hundreds of meters. This is illustrated in the figure below. The position of the Texas capitol building is described using identical latitude and longitude on all maps, but because the model for the shape of the earth differs between the maps, the position of the capitol building also differs.</p>
<p><img src="images/coordinateSystem/datumDifferences.png"></p>
<p>Figure x</p>
<p>It’s quite easy to come across a map that does not use WGS-84. Even though the US government has a National Geospatial Intelligence Agency responsible for mapping, the reality is that LVC simulations often use maps or geo-referenced entities from who knows what source. This may manifest itself in LVC simulations when a convoy is shown on a map driving near a road, but with a 20 meter offset. The position of the vehicles is a live component, reported using GPS, which uses WGS-84. The map the entities are displayed on uses a different datum. When GPS reports latitude and longitude it winds up being in a different 3D location than the map’s concept of the road’s location.</p>
<p>There are also some computational issues. When using units of meters geocentric coordinate system values can be over six million meters, and this can cause some numeric precision problems if using single precision floating point numbers. Doing the math required to convert between coordinate systems discussed below can result in computational roundoff errors. Stick to double precision.</p>
<h3 id="terrain">Terrain</h3>
<p>The earth is not smooth, and terrain can rise above or below the geoid, as Mount Everest, the Dead Sea, or the bottom of the Atlantic Ocean do.</p>
<p>Terrain is a tricky problem in itself and outside the scope (for now) of this document. Simulations need precise placement of objects, often to sub-meter accuracy. Getting agreement on this between simulations that use terrain information from different sources is very difficult. Most simulations hack this lack of accuracy by using <em>ground clamping</em>. If an entity such as a tank is described by a companion simulation as being a meter above the ground on the local simulation, the local simulation will simply force it to be drawn as in contact with the ground. This avoids the problem of “hover tanks” that appear to float above the terrain, an artifact that would undermine user confidence in the simulation. But this also means that the position of the entity differs from what the simulation that owns the entity is describing.</p>
<h3 id="prefab-packages">Prefab Packages</h3>
<p>There are several packages that convert between the coordinate systems discussed above–geocentric, geodetic, MGRS, and the local coordinate system attached to a maneuvering F-16’s center of gravity. One popular package is the SEDRIS SRM package.</p>
<p><a href="http://www.sedris.org/srm_desc.htm">Sedris SRM site</a></p>
<p>The SEDRIS site includes tutorials about the theory behind the process and also tutorials about using the Java and C++ packages they provide. If you’re doing serious work with position, orientation, and velocity then a prefab package that handles the conversions is highly recommended. You probably shouldn’t trust the math I discuss below all that much.</p>
<h3 id="coordinate-system-transformations-latitude-and-longitude-to-geocentric">Coordinate System Transformations: Latitude and Longitude to Geocentric</h3>
<p>Especially in naval simulations it’s popular to describe the position of entities using latitude, longitude, and altitude. We need to convert between latitude and longitude and the geocentric coordinate system.</p>
<h3 id="shut-up-and-give-me-the-equation">Shut up and give me the equation</h3>
<p>To convert latitude, longitude, and altitude to the DIS geocentric (“Earth-Centered, Earth Fixed”) coordinate system:</p>
<p><img src="images/LatLonAltToECEF.jpg"></p>
<p>Remember, angles are in radians here. Alpha is latitude, omega is the longitude, a is the semi-major axis of the WGS-84 specification, 6378137, and b, the semi-minor axis of WGS-84, is 6356752.3142.</p>
<p>Converting from DIS coordinates to latitude, longitude, and altitude is a little trickier.</p>
<p>First, longitude:<br> <img src="images/LongitudeFromXYZ.jpg"></p>
<p>Next, latitude. This can be done iteratively for better precision but one iteration gives about five decimal places of accuracy:</p>
<p><img src="images/LatitudeFromXYZ.jpg"/></p>
<p>Finally, altitude:<br> <img src="images/AltitudeFromXYZ.jpg"/></p>
<h3 id="by-give-me-the-equation-i-meant-give-me-the-source-code">By “Give Me the Equation” I Meant “Give Me the Source Code”</h3>
<p>A Javascript implementation of coordinate conversion is <a href="https://github.com/open-dis/open-dis-javascript/blob/master/javascript/disSupporting/CoordinateConversion.js">here</a></p>
<p>The Javascript code to set up a local tangent plane coordinate system is <a href="https://github.com/open-dis/open-dis-javascript/blob/master/javascript/disSupporting/RangeCoordinates.js">here</a></p>
<h3 id="orientation">Orientation</h3>
<p>We can place an entity in the world, but how do we know which way it’s facing? In the case of DIS, the convention is to express entity location in terms of sequential rotations about coordinate axes.</p>
<p>The record expressing orientation has fields for psi, theta, and phi. These represent angles, expressed in radians, in the entity’s global coordinate system. First, rotate psi radians around the z-axis which points out the north pole in the DIS coordinate system. Then rotate theta radians around the y-axis, and finally phi radians around the x-axis. The final state, after three rotations, is shown in the image below:</p>
<p><img src="images/EulerAngles.jpg"/></p>
<p>The Austalian Defense Force has published a fine paper on the mathematics involved, including the use of quaternions to aid in computation. See the Kok paper below in “further readings.”</p>
<p>https://discussions.sisostds.org/index.htm?A3=ind0210&amp;L=Z-ARCHIVE-SISO-ENUM-2002&amp;E=quoted-printable&amp;P=7277&amp;B=–&amp;T=text%2Fhtml;%20charset=UTF-8&amp;pending=</p>
<p>Consider two cases: we want convert a position and orientation of a vehicle at the Naval Postgraduate School in Monterey to the standard used by DIS, and convert the values we get from DIS in a state update to position, with roll, pitch, and heading. It’s at 36.5973° N, 121.8731° W, altitude 5 m, and it’s pointing +20 degrees from north, with a 5° roll and a 10° pitch.</p>
<p>First of all, we need the postion of the entity as expressed in DIS (aka ECEF) geocentric coordinates. The equation for this is above. There’s also an online calculator at <a href="http://www.apsalin.com/convert-geodetic-to-cartesian.aspx">an online source</a>. The ECEF coordinates are (-2707135.985, -4353750.737, 3781611.558) for that latitude, longitude, and altitude. Next we need to find a coordinate base system rotated to the same orientation as the vehicle (using the NED convention, North=x, East=y, Down=z.)</p>
<h3 id="tangent-planes">Tangent Planes</h3>
<p>Set up a local tanget plane</p>
<h3 id="entity-local-coordinate-systems">Entity Local Coordinate Systems</h3>
<p>In addition to the global coordinate system, which are used to position entities in the real world, DIS sometimes uses a local coordinate system to describe items relative to the entity in question. A local coordinate system has its origin at the center of the entity’s <em>bounding volume</em>. A bounding volume is a closed volume that completely contains the entity. If there’s a tank with a complex shape, then a bounding volume might be a box large enough to completely contain the tank. It’s useful for creating a computationally efficient algorithms that discover things like entity collisions, and for certain graphics calculations relating to view frustums. In the context of DIS the local coordinate system can be used to describe where, specificaly, a munition impacted on an entity.</p>
<p>The local coordinate systems x-axis points out the front of the entity, the y-axis out the right hand side, and the z-axis points down, in a conventional right-handed coordinate system arrangement.</p>
<h3 id="further-reading">Further Reading</h3>
<p>Sedris SRM package: <a href="http://www.sedris.org/srm_desc.htm">Sedris SRM site</a><br></p>
<p>SRM Tutorial: <a href="https://www.youtube.com/watch?v=mFFfO-NJMFI">Youtube Tutorial</a><br></p>
<p>SRM Tutorial, hardcopy: <a href="http://www.sedris.org/stc/2000/tu/srm/tsld003.htm">Hardcopy slides</a><br></p>
<p>DTIC manual for coordinate system transformations: <a href="http://www.dtic.mil/dtic/tr/fulltext/u2/a307127.pdf">DTIC Manaul</a><br></p>
<p>Coordinate System Transformation theory: <a href="http://www.springer.com/cda/content/document/cda_downloaddocument/9780857296344-c2.pdf?SGWID=0-0-45-1143141-p174116371">Book Chapter</a></p>
<p>“Using rotations to build aerospace coordinate systems”, Kok: <a href="documents/UsingRotationsToBuildAerospaceCoordinateSystems.pdf">Australian Defence Force paper</a></p>
<p>WGS precision: https://tools.ietf.org/html/rfc7946</p>
<p>Datums effect on positons: http://www.geo.utexas.edu/courses/371c/Lectures/Fall14/Datums_GCSs_Spring14.pdf</p>
